Contents
VCLZip 2.22, The Native Delphi Zip/UnZip Component

TVCLZip Component	TVCLUnZip Component

Installing

Registering VCLZip

What's New in this version / Version History

Quick Reference:

Properties

Methods

Events List

Creating a Zip File

UnZipping Files

Creating Spanned Disk Zip Files

Creating Blocked Zip Files (Creating Spanned Disk Images directly to hard drive)

Using Streams

UnZipping to Memory Buffers

Zipping from Memory Buffers

Creating a Self Extracting Zip File

Working with wildcards

Streamlining Your Application

Frequently Asked Questions

Compiler Options Settings

Acknowledgments

Be sure to check one of the following:

http://www.bigfoot.com/~boylank   (This one will always map to the correct URL)

http://vclzip.bizland.com or

http://members.nbci.com/boylank

for any additional for newer files.

What is VCLZip?

The VCLZip Delphi component allows you to add ZIP and UNZIP capabilites to your application. This component is different from most other "ZIP" development libraries in that it is written in 100% Delphi Object Pascal code and is full featured.  There are no DLL's to tote around.  This component links right into your application's executable. It is very easy to use.  Just SOME of the features include:

•	Create zip files fully compatable with PKZip

•	Completely native Delphi VCL  (NO DLLS!!!!!!!!!!!)

•	Create Disk Spanning and Blocked zip files

•	Delphi 1, 2, 3 and 4 compatible

•	C++ Builder 1, 3, and 4 compatible

•	Zip directly from streams to zip files

•	Unzip directly to streams from zip files

•	Stream to Stream zipping and unzipping

•	Unzip directly to memory buffers

•	Zip directoy from memory buffers

•	Create and read Zip and File Comments

•	Create Self Extracting Zip Files (16 bit and 32 bit distributable

•	windows sfx stubs included (source not included for these) or use your own stubs)

•	Complete support for encrypted files (encrypts as it zips)

•	Save Relative Path information

•	Unzip using Relative Paths (even if zip file wasn't created with relative path info)

•	Exclude List (tell VCLZip which files not to include (use wildcards too))

•	NoCompress (STORE) List (tell VCLZip which files to just store (use wildcards too)

•	Set your own temp directory

•	Plenty of events

•	Long filenames, even the 16 bit VCLZip/VCLUnZip

•	Includes comprehensive Zip Utility with source as demo

•	Includes a small stream zipping demo

•	Includes a context sensitive help file

•	No Royalties!

•	Priced at only $49.95 per developer!!!

VCLZip constists of two components.  TVCLUnZip which handles all of the viewing and unzipping responsibilities and TVCLZip which descends from TVCLUnZip and adds all of the zipping features.

If your application requires both zip and unzip capabilities, just drop TVCLZip onto your application's form.  If all your application needs is unzipping capabilities then all you will need is the TVCLUnZip component.  You should never need both components at the same time for most purposes.

VCLUnZip and VCLZip works in both the 16 and 32 bit environments.

Also,  VCLZip fully supports Spanned Disk Zip Files as well as Blocked Zip Files.

All versions support long filenames completely.  Even the 16 bit version of the VCLZip component will unzip files with long filenames and long directory names.

Registering VCLZip will get you all of the source code.  The unregistered version will only work while the Delphi/BCB IDE is running.

** Please test the component out completely to your satisfaction before registering to be sure that it meets your requirements.  I do not guarantee that it is completely free from bugs.  This component has been well tested, but certainly not under all conditions.

Included in this installation is a fully functional component.  When you register you will receive instructions for where to download a new installation containing all of the source code.  Once you install the components using the source code, you will be able to run your application outside of the Delphi/BCB IDE. You will also be put on a mailing list so that I can notify you of any upgrades or bug fixes. You will receive point releases at no charge.  You will also receive discounts on any major upgrades.

There is also a very complete zip utility which is useful as an example of how to use the component.  With the example you can open and view zip files, extract files from zip files, add files, create new zip files and even view files from within the zip files by double-clicking on any compressed file.  You can also add and modify file and zip comments as well as create self extracting zips and fix truncated zip files and even create and read Spanned Disk Sets and Blocked Zip Files.  Both 16 and 32 bit Windows self extracting stubs are supplied, however VCLZip will create an SFX file with any stubs you supply.

Please let me know of any bugs that you might find.  See the contact information below.

Pricing and Support Philosophy

I am trying to keep the price very low so as to make zip capabilites available to developers that can't afford the almost $200 price tags of most full featured ZIP libraries on the market today.

Email support is available.  I will do my best to fix any bugs that are found AND to add any enhancements that you think would make this component more productive.  While I can't provide a 'round the clock' help desk support, I will do the best I can.

Contact

Please feel free to test this component thoroughly before registering.  I'll be glad to answer any questions you might have, just email me at

boylank@bigfoot.com

This address redirects mail to more than one of my email accounts so please to not be alarmed if you ever get a delivery failure message.  Chances are that your message made it to more than one of my accounts.

The latest evaluation version of VCLZip and up-to-date information can be found on the WWW at

http://www.bigfoot.com/~boylank   (This one will always map to the correct URL)

http://ourworld.compuserve.com/homepages/boylank or

http://members.xoom.com/boylank

This help file was compiled: 7/21/01


Examples
Using TVCLUnZip

Basic procedure for programming the VCLUnZip component:

If you simply wish to extract all files from a particular zip file it is as easy as just specifying the ZipName and DestDir properties and then call the UnZip method.  That's it.  If you wish to do more, the following pseudo example gives a very cursory overview of the kinds of  things you can do...

MemoPad: TMemo;

Unzipper: TVCLUnZip;

NumUnzipped: Integer;

USES ... VCLUnZIp, kpZipObj;  <-kpZipObj is needed if you use some of the defined types ...

With Unzipper do

begin

ZipName := 'c:\test\Zipfile.zip'    // set the zip filename

ReadZip;                           // open it and read its information

// List filenames in zip file

for i := 0 to Count-1 do

MemoPad.Lines.Add( Filename[i] + #9 + Pathname[i] );

// extract some files

// determine which files to unzip

FilesList.Add( '*.cpp' );              // unzip all .cpp files

FilesList.Add( 'myprog.exe' );   // unzip myprog.exe

FilesList.Add( '?<0-9>*\*.h' );      // .h files, if 2nd letter of dir starts with digit only

FilesList.Add( Filename[Count-1] );   // extract last entry in zipfile

DoAll := False;                  // Don't unzip all files

DestDir := 'c:\mydir'         // Set destination directory

RecreateDirs := False;     // don't recreate directory structures

RetainAttributes := True   // Set attributes to original after unzipping

NumUnzipped := Unzip;                        // Extract files, return value is the number of files actually unzipped

end;


Properties
VCLUnZip Properties

Public:

Indexed Properties (apply to each compressed file):

Filename

Pathname

FullName

CompressMethod

CompressMethodStr

DateTime

Crc

CompressedSize

UnCompressedSize

IsEncrypted

FileHasComment

FileComment

ExternalFileAttributes

DiskNo

Selected

DecryptHeader

FileIsOK Property

Non-Indexed Properties (apply to the archive):

Count

ZipComment

Password

ZipHasComment

NumDisks

ZipSize

CheckDiskLabels

MultiMode

ArchiveStream

Busy

NumSelected

BufferLength

Published:

ZipName

DestDir

RootDir

SortMode

RecreateDirs

OverwriteMode

FilesList

DoAll

IncompleteZipMode

KeepZipOpen

DoProcessMessages

RetainAttributes

ThisVersion

ReplaceReadOnly


PG5
 VCLUnZip Events

OnStartUnzipInfo

OnFilePercentDone

OnTotalPercentDone

OnStartUnZip

OnEndUnZip

OnPromptForOverwrite

OnSkippingFile

OnBadPassword

OnBadCRC

OnInCompleteZip

OnGetNextDisk

OnUnZipComplete

OnGetNextBuffer


PG6
 VCLUnZip Methods

ReadZip

UnZip

UnZipSelected

UnZipToStream

UnZipToStreamByIndex

UnZipToBuffer

UnZipToBufferByIndex

ClearZip

FillList

Sort

CancelTheOperation

ResetFileIsOK

ClearSelected

CheckArchive

GetDecryptHeaderPtr

GetDecryptHeaderByteByPtr


TVCLUnZip
TVCLUnZip Component

Properties	Methods	Events	Example

Description

The VCLUnZip component handles all unzipping responsibilities.  VCLUnZip is the base class for the VCLZip component.

Note that all properties, methods, and events that apply to VCLUnZip will also apply to VCLZip.

NOTE: If you only need to do UNZIPPING operations then you will only need the VCLUnZip component.  This will reduce your applications footprint over using the VCLZip component which handles both unzipping and zipping operations.

See TVCLZip


RelativePaths
RelativePaths Property

Applies to

TVCLZip

Declaration

property RelativePaths : Boolean;

Description

The RelativePaths property should be set to True if you wish to save path information but only wish to save path information relative to a specified directory.  The only path information that is saved is for subdirectories below the specified directory.  This is similar to the Relative Path option of PKZip for Windows.

Whenever you set RelativePaths property to True, the Recurse Property and the StorePaths Property are automatically set to True also.  Likewise, if the StorePaths Property is set to False, then the RelativePaths Property is automatically set to False also.

You would normally use a wildcard to specify files to be zipped, but you may also add specific files to the FilesList as long as they are within the directory tree of the RootDir.

If you add to, or replace files in, an existing archive which was created with the relative path option you should set the RootDir property to the same value that was used when the archive was created before calling the Zip method.

When storing relative paths it is NECESSARY to use the RootDir Property to specify the directory in which to start the recursive search for files to compare to some wildcard filespec.  Here is an example of using the RelativePaths property:

With VCLZip1 do

begin

ZipName := 'c:\backups\MyArchive.Zip';

RootDir := 'c:\develop\myprog\';	/* Set the starting directory */

FilesList.Add('*.pas');	/* Don't include path here */

RelativePaths := True;	/* Specify Relative Paths - sets StorePaths & Recurse to True also*/

Zip;

end;

Say the directory structure looks something like the following:

\develop\myprog

\develop\myprog\help

\develop\myprog\examples

\develop\myprog\proj

\develop\myprog\proj\save

Files zipped from each of these directories will have the following path information stored depending on how RelativePaths is set:

RelativePaths = False	RelativePaths = True

develop\myprog\	None Saved

develop\myprog\help\	help\

develop\myprog\examples\	examples\

develop\myprog\proj\	proj\

develop\myprog\proj\save\	proj\save\


What's New
Version History 2.18 and Earlier

Version 2.18:

1) Made VCLZip completely BCB4 compatible.

2) Moved several type definitions to VCLUnZip.PAS, eliminating the need for you to include KPZIPOBJ in your Added the option to define the conditional MAKESMALL which removes all dependencies on the Dialogs, Forms, Controls, and FileCtrl units, which results in a much  smaller footprint.  This can be quite useful when putting VCLZip into a DLL for instance.  In order to make this work, go into your Project | Options and select the Directories/Conditionals tab and enter MAKESMALL in the conditional defines text box.  In Delphi you can add this conditinal define to the project options of your application that uses VCLZip and then do a "build all".  In BCB you will have to add this to the project options of the package that contains VCLZip and then rebuild the package.

If you define MAKESMALL, the only things you lose are:

a) ZIP file open dialog box that appears when the ZipName is set to "?" b) Select Directory dialog box that appears when the DestDir is set to "?" c) Changing the cursor to an hour glass during some operations. d) No long filename support in Delphi 1

3) Added some exception handling to KPUNZIPP and KPINFLT, mainly to handle unexpected situations when wrong passwords are entered. This fixes the problem with PRP, the password recovery program.

4) For Borland C++ Builder, changed any COMP types to double, getting rid of the compiler warnings for unsupported comp type.  This affects the OnStartZipInfo and OnStartUnzipInfo events, so you'll have to change the comp parameter to double in these events if you use them (in both your header files and in the CPP files.)

5) Modified OnStartUnZip event so that FName (the filename of the file that is about to be unzipped along with complete path) is now a VAR parameter and can be modified.   This allows you to change the path and name of a file that is about to be unzipped.  This is especially helpfull in applications like Install Programs. NOTE: You will need to change your current code to add the VAR to the event definition and implementation if you already use this event in your application. (In BCB, add a & just before the parameter instead of VAR)

6) Moved many type definitions to VCLUNZIP.PAS so that kpZipObj won't have to be included in your USES list.  You will still need to include kpZipObj for certain things, for instance if you use the OnStartUnZip event since TZipHeaderInfo is defined in kpZipObj.

7) Fixed bug that caused GPF when setting ZipComment to ''.

8) Moved strings in VCLZip/VCLUnZip into a string table, making the code size a little smaller as well as making it much easier to localize string information.  However you have the option of not using the new string table, for whatever reason, by defining NO_RES in your project options (in the conditional defines text box on the Directories/Conditionals tab).

9) Removed the need for several files.  No longer included are kpstrm.res, kpstrm.rc, kpsconst.res, kpsconst.rc, kpstres.pas, and for Delphi 1, kpdrvs.pas.  In some cases the need for these files was eliminated and in other cases just rolled into the newly included kpzcnst.rc, kpzcnst.pas, and kpzcnst.res.  Definining NO_RES in your project options will elimiate the need for these new files but will make your code size slightly larger and you won't be able to localize your application without changing VCLZip source code.

10) Modified the OnFilePercentDone and OnTotalPercentDone progress events to work better when creating spanned and blocked disk sets.  They no longer report 100% when the compressed file still has to be copied to disk.

11) Added the ReplaceReadOnly property.  Setting this to true will allow files with the ReadOnly attribute to be replaced during the unzip process.

12) Added the ifNewer and ifOlder options to the OverwriteMode property. (This had somehow previously made it into the help file but not into VCLUnZip)

13) Added the SFXToZip method which will convert an SFX file to a regular zip file. The header pointers will be properly adjusted during the conversion.

14) Fixed a problem where the OnGetNextDisk Event would always revert to the DefaultGetNextDisk method instead of what you entered into the Object Inspector each time your project was re-opened.

15) Fixed a bug that caused CRC errors when unzipping files from spanned disk sets if they were STORED (no compression) and spanned across disks.

16) Added the OnZipComplete and OnUnZipComplete events.  If defined, these will fire at the very end of a zip or unzip operation (after all files have been processed, not after each file).  These events will rarely be used since, normally you will be able to do the same thing at the point that the call to Zip or UnZip returns, but these events can be useful when using VCLZip in threads where in certain circumstances the return from the Zip or UnZip methods are not seen.

17) Creation of SFX files has never been easier!!!  The addition of the MakeNewSFX method allows you to create Self Extracting Executables without the need to create a zip file first.  The files that you specify in the FilesList Property will be zipped, using all of the VCLZip property settings,  and the SFX will be created, all in one step!  In addition, you can create configurable SFX files using this method, and you can do this especially easy by adding the new unit kpSFXOpt to your application's USES list and using the new 32bit SFX stub that is now distributed with VCLZip.  This allows you to easily set things like SFX Dialog caption, default target extraction directory,  file to launch after extraction, etc.

18) Fixed a memory leak that only affects applications using VCLZip that are compiled with Delphi 2, and that use wildcard specifications in the FilesList Property.

Version 2.17a:

Fixed a bug that was keeping VCLZip from reading truncated zip files or sfx files that did not have their headers adjusted.

Fixed a bug that was causing a directory to be created on the C drive when doing integrity checking with the FileIsOK property.

Added $V- to kpZipObj.PAS

Moved two AssignTo methods to public instead of private in kpZipObj.PAS

Version 2.17:

Added Memory zipping and unzipping capabilities through the UnZipToBuffer and ZipFromBuffer methods.

New FileIsOK Property allows you to check for the integrity of individual files within an archive without actually unzipping the file.

Fixed a bug that kept checking of volume labels from working on WIN31 when working with spanned disk sets.

Removed all references to ChDirectory so that VCLZip will be more thread safe allowing separate instances of VCLZip in separate threads to be performing zip/unzip operations at the same time.

A new public property PreserveStubs allows you to make modifications to sfx archives and have the archive remain an SFX rather than revert back to a normal zip file.

Added a default OnGetNextDisk event.  If one is not defined, then the default event will be called when the situation arises that a new disk is needed when zipping or unzipping a spanned or blocked zip archive.

Added more power to the wildcard capabilities.  Now you can qualify the * wildcard character, for instance:

*<a-e> would satisfy any number of contiguous characters as long as they are all a thru e.

*<!a-e> would satisfy any number of contiguous characters as long as none of them were a thru e.

This allows you to do things like include files in specific direcories into your ExcludeList.  For instance:

VCLZip1.ExcludeList.Add('c:\test\*<!\>.txt')

would exclude the zipping of all .txt files in the test directory but not in any subdirectories.

Version 2.16:

The OnSkippingFile Event has been changed slightly, adding a parameter for the filename.

OnSkippingFile is now called when a file to be zipped is skipped because it is locked by another application.

Version 2.15:

The PackLevel Property now allows you to set a level of 0, which means that files will only be STORED with no compression when zipping.

New property ExcludeList allows you to specify files that you do not wish to be included in archives when zipping.

New property NoCompressList allows you to specify files that you wish VCLZip to STORE only (no compression) when zipping, regardless of what PackLevel is set at.

Version 2.14:

Delphi 4 Compatability

Wildcards can now be much more complex when zipping, including wildcards in the path part of a filename.

You may now override the Recurse property when you add files and wildcards to the FilesList property for zipping by prepending the filespecs with either '>' or '|'.

The [ and ] characters previously used as special Wildcard characters have been changed to < and > since [ and ] are valid filename characters.  If you still need to use the previous characters for backward compatability, I can show registered users how to easily modify a couple of constants in the source code in order to go back to the old style.

Version 2.13:

New property ResetArchiveBitOnZip causes each file's archive bit to be turned off after being zipped.

New Property SkipIfArchiveBitNotSet causes files who's archive bit is not set to be skipped during zipping operations.

A few modifications were made to allow more compatibility with BCB 1.

Version 2.12:

New property TempPath allows temporary files to be created in a directory different from the default TEMP directory.

Version 2.11:

Bug fixes only.  See readme.txt file for details.

Version 2.10:

16 bit VCLZip now stores long file and path names in archives when running on a 32bit OS.

New property Store83Names allows you to force file and pathnames to be stored in DOS 8.3 format.

Better UNC path support.

Fixed a bug allowing files to be added to an empty archive.

Version 2.03:

Bug fixes only.  See readme.txt file for details.

Version 2.02:

ThisVersion is a new property which reflects the version number of the current VCLZip/VCLUnZip that you are working with.

Version 2.01:

No new features for this version.  Bug fixes only.

Version 2.00:

RelativePaths is a new VCLZip property giving you the option to store relative path information for each file instead of complete path information.

RootDir will now allow you to extract files from an archive that was not previously compressed using the RelativePaths property as if it had been.

ArchiveStream is a new VCLUnZip property allowing you to work with archives as in-memory TStreams. The Stream Demo now uses this property.

OnStartZipInfo Event now allows you to add a zip comment to a new archive.

OnStartZip Event now allows you to modify information that is stored with each file just before it is zipped.

OnBadPassword Event now allows you to reset the password and retry the same file again.

DateTime Property is now also writable along with Filename and Pathname

Busy Property is a new property set to True during Zip and UnZip operations.

VCLZip is now Delphi 1 compatible.

VCLZip will no longer include the archive that is currently being created in itself if it is being created in the same directory as files are being zipped from.


ReadZip
ReadZip Method

Applies to

TVCLUnZip

Declaration

procedure ReadZip;

Description

The ReadZip method causes the zip file to be opened and all pertinant information to be read from the zip file.  The information on each file can be accessed by the indexed properties described later.  You should call this procedure after setting the ZipName property. This procedure only needs to be called if you plan to access the files information such as Filename[Index] before performing an operation.  You can call the UnZip or Zip or any functions without calling ReadZip first.

If KeepZipOpen is set to False, ReadZip will open the zip file, read it's information and then close the zip file.  If this is the case, should the zip file change before the next time you perform an operation on it, the zip's information will automatically be updated.


ArchiveStream Property

Applies to

TVCLUnZip

Declaration

property ArchiveStream : TStream;

Description

The ArchiveStream property allows you to set the archive with a TStream or one of it's decendants rather than setting the archive with a disk file using the ZipName Property.  This lets you save archives in streams like database blob streams for instance or simply use faster in memory archives providing memory to memory compression and decompression.

You should use the ArchiveStream or the ZipName property but not both when specifying the zip archive.

IMPORTANT: You should either let VCLUnZip Free the stream for you (which it will do anytime you call ClearZip or set the ZipName property) or you should set ArchiveStream to nil after you Free it yourself so that VCLZip won't try to double Free it.  If you just pointed ArchiveStream at a stream of your own and you wish to keep that stream open, then simply set ArchiveStream to nil so that your stream won't be closed by VCLZip.

Setting the ArchiveStream property will also cause the KeepZipOpen Property to be set to True so that the TStream will not be Free'd in between operations.

ArchiveStream can be a new archive (set it using a new empty stream) or it can be an existing archive.

As an example of creating a new archive in memory using a TStream:

With VCLZip1 do

begin

ArchiveStream := TMemoryStream.Create;	/* Create archive in a memory stream */

FilesList.Add('c:\mydir\*.*');	/* zip all file in directory */

Zip;	/* this zips files into an archive in ArchiveStream, a memory stream */

end;

Remember, if you want to save the archive that you have created in the ArchiveStream, you will have to save the ArchiveStream to a file yourself.  While you are working with ArchiveStream do not also reference ZipName since a memory stream does not have a filename ofcourse.


Busy
Busy Property

Applies to

TVCLUnZip

Declaration

property Busy: Boolean;

Description

The Busy property will be True during any UnZip or Zip operations.  Checking this will allow you to start an operation, go on and do something else while the operation is executing in the background.  If you write your application in this way, check to be sure this property is False before beginning another operation.

IMPORTANT:  Do not try to modify any of VCLZip or VCLUnZip's properties while the Busy property is True.  You may do some background processing, but don't try to modify any properties during this time since those properties are still being used by the component.

In order for this property to have any meaning when True, the DoProcessMessages Property should be set to True also.  Otherwise the Zip or UnZip operation won't relinquish control of the CPU for you to do other things.


UnZip
UnZip Method

Applies to

TVCLUnZip

Declaration

function UnZip: Integer;

Description

The UnZip method causes the files defined in FilesList property to be extracted.  If FilesList is empty then all files in the zip file are extracted.  The return value is the number of files successfully unzipped.


ClearZip
ClearZip Method

Applies to

TVCLUnZip

Declaration

procedure ClearZip;

Description

The ClearZip method removes all of the zip information from memory.  The component is still ready to open another zipfile, or even the same zip file.  Opening another zipfile will take care of this for you so this is usually optional.


FillList
FillList Method

Applies to

TVCLUnZip

Declaration

procedure FillList( FilesList: TStrings );

Description

The FillList method fills the string list with tab delimited information on each file.  Useful if you want to display information on all files in a listbox.  It is usually best to just used the indexed properties so that you can fill the fileslist the way you want.


Sort
Sort Method

Applies to

TVCLUnZip

Declaration

procedure Sort( SMode: TZipSortMode );

TZipSortMode = (ByName, ByFileName, ByDirectoryName, ByDate, ByCompressedSize, ByUnCompressedSize, ByRate, ByNone);

Description

The Sort method sorts the zip information according to SortMode Property.  The default sort mode is ByNone.

WARNING

If you are working with a multi-part zip file, it is most efficient to have the zip information sorted with SortMode = ByNone.  If you have the information sorted by any other mode and you are working with a mulit-part file, the component will have to sort the information using the ByNone mode and then sort the information back to the way you had it sorted.   This will only be noticable on zip files containing a large number of entries.


CancelTheOperation
CancelTheOperation Method

Applies to

TVCLUnZip

Declaration

procedure CancelTheOperation;

Description

The CancelTheOperation method causes the current zipping or unzipping operation to be canceled.  This is useful if you wish to abort a very long operation before it is finished.  If the DoProcessMessages Property is set to False, calling this procedure will have no effect.


UnZipToStream
UnZipToStream Method

Example

Applies to

TVCLUnZip

Declaration

function UnZipToStream( theStream: TStream;  theFIle: String ): Integer;

Description

The UnZipToStream method unzips the file specified by theFile parameter from the zip file specified by the ZipName Property directly to the stream specified by theStream parameter.


Count
Count Property

Applies to

TVCLUnZip

Declaration

property Count : Integer

Description

The Count property returns the number of files in the Zip file.


PG32
 Pathname

FullName


Filename
Filename Property

See also

Applies to

TVCLUnZip and TVCLZip

Declaration

property Filename [ Index ]: String;

Description

The Filename property returns just the filename portion of the file, without the path. TZipFilename type is just a String type.

If you are using VCLZip, this property is also writable.   Once you have opened up a zip file you may set this property, thereby modifying what is already contained by this property.  It is up to you to be sure not to modify this in such a way that you would end up with two files in the zip archive with the same Filename and Pathname.

If you do set Filename, the archive will be flagged as modified.  After setting all of the Filenames that you wish to set, you should call the SaveModifiedZipFile Method to save the archive with the new Filenames.

Reading Filename:

ThisName := VCLZip.Filename[i];

Writing Filename:

VCLZip.Filename[i] := NewName;

SaveModifiedZipFile;


PG35
 Filename

FullName


Pathname
Pathname Property

See also

Applies to

TVCLUnZip and TVCLZip

Declaration

property Pathname [ Index ]

Description

The Pathname property returns just the pathname portion of the file, without the filename.  This does include a '\' at the end.

If you are using VCLZip, this property is also writable.  Once you have opened up a zip file you may set this property, thereby modifying what is already contained by this property.  It is up to you to be sure not to modify this in such a way that you would end up with two files in the zip archive with the same Filename and Pathname.

If you do set Pathname, the archive will be flagged as modified.  After setting all of the Pathnames that you wish to set, you should call the SaveModifiedZipFile Method to save the archive with the new Pathnames.

Reading Pathname:

ThisPath  := VCLZip.Pathname[i];

Writing Pathname:

VCLZip.Pathname[i] := NewPath;

SaveModifiedZipFile;


FullName
FullName Property

See Also

Applies to

TVCLUnZip

Declaration

property FullName [ Index ]

Description

The FullName property returns the full path and filename of the file.  Same as  Pathname[Index] + '\' + Filename[Index].


CompressMethod
CompressMethod Property

Applies to

TVCLUnZip

Declaration

property CompressMethod [ Index ]

Description

The CompressMethod property returns the compression method of the particular file.

Be sure to include kpZipObj in your USES list if you plan on including any of the following in your application.

Return value:

STORED =       0;

SHRUNK =       1;

REDUCED1 =   2;

REDUCED2 =   3;

REDUCED3 =   4;

REDUCED4 =   5;

IMPLODED =    6;

TOKENIZED =   7;

DEFLATED =    8;


CompressMethodStr
CompressMethodStr Property

Applies to

TVCLUnZip

Declaration

property CompressMethodStr [ Index ]

Description

The CompressMethodStr property returns a string representation of the compression method for the particular file. The strings returned will be one of the following:

STORED =	'STOR'

SHRUNK =	'SHR'

REDUCED1 =	'RED1'

REDUCED2 =	'RED2'

REDUCED3 =	'RED3'

REDUCED4 =	'RED4'

IMPLODED =	'IMP'

TOKENIZED =	'TOK'

DEFLATED =	'DEF'

Be sure to include kpZipObj in your USES list if you plan to use any of the above in your apps.


DateTime
DateTime Property

Applies to

TVCLUnZip and TVCLZip

Declaration

property DateTime [ Index ]

Description

The DateTime property returns the Date and Time stamp for the particular file in TDateTime format.  If using VCLZip you may also set this value to change the Date and Time stamp for a file in an existing archive.

If you do set DateTime, the archive will be flagged as modified.  After setting all of the DateTime's that you wish to set, you should call the SaveModifiedZipFile Method to save the archive with the new DateTime's.

Reading DateTime:

ThisTime := VCLZip.DateTime[i];

Writing DateTime:

VCLZip.DateTime[i] := Now;

SaveModifiedZipFile;


Crc
Crc Property

Applies to

TVCLUnZip

Declaration

property Crc [ Index ]

Description

The Crc property returns the CRC for the particular file that is stored in the zipfile.


CompressedSize
CompressedSize Property

Applies to

TVCLUnZip

Declaration

property CompressedSize [ Index ]

Description

The CompressedSize property returns the compressed size of the file.


UnCompressedSize
UnCompressedSize Property

Applies to

TVCLUnZip

Declaration

property UnCompressedSize [ Index ]

Description

The UnCompressedSize property returns the uncompressed size of the file.


IsEncrypted
IsEncrypted Property

Applies to

TVCLUnZip

Declaration

property IsEncrypted [ Index ]

Description

The IsEncrypted property returns True if the compressed file is password encrypted.

See Also:

Password

OnBadPassword Event


FileHasComment
FileHasComment Property

Applies to

TVCLUnZip

Declaration

property FileHasComment [ Index ]

Description

The FileHasComment property returns True if the particular file has a comment.

See Also:

FileComment

ZipComment

SaveModifiedZipFile Method


FileComment
FileComment Property

Applies to

TVCLUnZip and TVCLZip

Declaration

property FileComment [ Index ]

Description

The FileComment property returns the comment for the specified file, if there is one. For 16 bit (Delphi 1) no more than 255 characters of the comment are returned.

When using the TVCLZip component, you can also assign a comment to the specified file.

See Also:

FileHasComment

ZipComment

SaveModifiedZipFile Method


DiskNo
DiskNo Property

Applies to

TVCLUnZip

Declaration

property DiskNo [ Index ]

Description

The DiskNo property returns the disk number of the specified file.  This is useful when working with multi-file zip files (DISK SPANNING).  The first file/disk in a multifile set is #1.  For single file zip files this will always return a 1, but for multi-file zip files it will return the actual disk that the compressed file begins on.

See Also:

Creating Spanned Disk Zip Files

Creating Blocked Zip Files


PG71
 FileComment

OnStartZipInfo

OnStartZip


ZipComment
ZipComment Property

See also

Applies to

TVCLUnZip and TVCLZip

Declaration

property ZipComment : String

Description

The ZipComment property returns the zipfile's comment if there is one.  For 16 bit (Delphi 1) no more than 255 characters of the comment are returned.

You may (as of version 2.19) simply set the ZipComment property directly, before calling any of the Zip methods when either creating a new zip file, or when adding or updating an existing zip file.  For instance:

With VCLZip1 do

begin

ZipName := 'c:\mydir\MyArchive.ZIP';

ZipComment := 'This is a comment';

FilesList.Add('c:\test\*.*'); FilesList.Add('c:\backups\*.*); Zip;

end;

If all you want to do is modify or add a zip comment for an existing archive (not zipping any additional files) then you should call the SaveModifiedZipFile Method to save the archive with the new ZipComment.

Something like the following:

With VCLZip1 do

begin

ZipName := 'c:\mydir\MyArchive.ZIP';

ReadZip;

ZipComment := 'This is a comment';

SaveModifiedZipFile;

end;

Keep in mind that you cannot add or modify a zip comment for an existing spanned or blocked archive. You cannot modify spanned or blocked archives in any way once they have been created.


Password
Password Property

Applies to

TVCLUnZip

Declaration

property Password : String

Description

If set to anything but a blank string, this password will be used when compressing data or uncompressing encryped files.

See Also:

setZipSignatures

OnBadPassword Event


ZipHasComment
ZipHasComment Property

Applies to

TVCLUnZip

Declaration

property ZipHasComment : Boolean

Description

The ZipHasComment property returns True if the zipfile itself has a comment.


NumDisks
NumDisks Property

Applies to

TVCLUnZip

Declaration

property NumDisks : Integer

Description

The NumDisks property returns the number of parts to the zip file.  Normally this will return 1, but if you are working with a spanned disk set or a multipart file, this will return the actual number of disks or parts.


ZipSize
ZipSize Property

Applies to

TVCLUnZip

Declaration

property ZipSize : LongInt

Description

The ZipSize property returns the size of the current zipfile specified by the ZipName Property in bytes.   If the zip file is a spanned archive, this property returns only the size of the currently open part of the archive.


PG89
UnZipToStream Method

ZipFromStream Method

ArchiveStream Property


ZipName
ZipName Property

See also

Applies to

TVCLUnZip

Declaration

property ZipName : String

Description

The ZipName property specifies the path and name of the zipfile that you plan to work with. This must, ofcourse, be set before you can do anything with or get information from the zipfile.  After setting the ZipName you should call ReadZip to cause the zipfile's information to be read (Calling ReadZip is optional if you do not plan to access the Indexed Properties before unzipping files. Performing any operation will cause ReadZip to be automatically called if it hasn't already been called).

Setting ZipName to a '?' will cause a fileopen dialogbox to be displayed so that a file can be selected.  If you set ZipName to '?' and the user presses the cancel button on the FileOpen dialog box, a EUserCanceled exception will be thrown and ZipName, along with all other properties will remain unchanged.  You may include a pathname along with the '?' if you wish the fileopen dialog box to begin in a certain directory.  For example

c:\backup\?

will cause a fileopen dialog box to be displayed beginning in the directory c:\backup


DestDir
DestDir Property

Applies to

TVCLUnZip

Declaration

property DestDir : String

Description

The DestDir property is  the path to where files will be extracted. If the path does not exist it will be created even if several levels of directories must be created.  In other words if DestDir is set to c:\dir1\dir2\dir3 and only c:\dir1 exists, dir2 and dir3 will be created.  It does not matter whether you include a '\' at the end.

If DestDir is set to a '?' then a directory finder dialog box will be displayed so that a directory can be selected. If you set DestDir to '?' and the user presses the cancel button on the dialog box, a EUserCanceled exception will be thrown and DestDir, along with all other properties will remain unchanged


SortMode
SortMode Property

Applies to

TVCLUnZip

Declaration

property SortMode : TZipSortMode

Description

Set this property to determine what order the information from the zipfile will be in when it is read.  In order to re-sort the information if it has already been read in, call the Sort method.

TZipSortMode = (ByName, ByFileName, ByDirectoryName, ByDate, ByCompressedSize, ByUnCompressedSize, ByRate, ByNone);

Note: ByName sorts by path+filename.


RecreateDirs
RecreateDirs Property

Applies to

TVCLUnZip

Declaration

property RecreateDirs : Boolean

Description

Set this property to True if you want to use directory information in the zipfile when extracting files.  The directories will be created relative to the DestDir (Destination Directory).  If this property is False, all files will be extracted to the DestDir, which could possibly result in files of the same name overwriting each other if the OverwriteMode property is set to Always.


OverwriteMode
OverwriteMode Property

Applies to

TVCLUnZip

Declaration

property OverwriteMode : TUZOverwriteMode

Description

Set OverwriteMode to determine what should be done if a file is about to be extracted and a file of the same name already exists in the destination directory.  The possible modes are

TUZOverwriteMode = (Prompt, Always, Never, ifNewer, ifOlder);   ( The default is Prompt )

Setting	Action Taken

Prompt	One of two things will happen.  If the OnPromptForOverwrite event is defined then it will be called and the application can decide whether to overwrite the file.  If the OnPromptForOverwrite event is NOT defined then the component will display a messagebox to allow the user to decide whether to overwrite the file.

Always	The file will be overwritten.

Never	Tthe file will not be extracted if it would overwrite a file.

ifNewer	The file will only overwrite the existing one if the archived file is newer than the existing one.

ifOlder	The file will only overwrite the existing one if the archived file is older than the existing one.


FilesList
FilesList Property

Applies to

TVCLUnZip

Declaration

property FilesList : TStrings

Description

Add filenames and/or wildcard specifications to this file list to specify what files will be extracted, added, or deleted from/to the zipfile.  If the property DoAll is set to True when extracting (calling UnZip) then the contents of this list will be ignored and all files will be extracted.  Also, if FilesList is empty when calling UnZip all files will be extracted, even if DoALL is not set to True.

Wildcards may be used when adding to the FilesList.  Also, it is possible to override the Recurse property by adding special characters at the beginning of any entry added to the FilesList.  See the Recurse property for more information.

As of version 2.20 VCLZip clears the FilesList after any zip or unzip operation, so the FilesList will be empty when after a call to any of the zip or unzip methods.


DoAll
DoAll Property

Applies to

TVCLUnZip

Declaration

property DoAll : Boolean

Description

If set to True then all files in the zipfile will be extracted when the UnZip Method is called.


IncompleteZipMode
IncompleteZipMode Property

Applies to

TVCLUnZip

Declaration

property IncompleteZipMode : TIncompleteZipMode

TIncompleteZipMode = (izAssumeMulti, izAssumeBad, izAssumeNotAZip);

Description

The IncompleteZipMode property determines how VCLZip will behave when a file that does not have an End Of Central Directory header is encountered.  This would mean one of the three following possibilities:

1. This is part of a multi-file zipfile and it is not the last file/disk in the set.

2. It is a bad zip file - corrupted or truncated

3. The file is not a zip file

How VCLZip behaves depends also on whether or not you have defined an OnIncompleteZip event.

See the OnInCompleteZip Event for complete details.


KeepZipOpen
KeepZipOpen Property

Applies to

TVCLUnZip

Declaration

property KeepZipOpen : Boolean

Description

Normally the zip file specified by ZipName is not kept open between operations.  By setting this property to True the file will remain open until you either call the ClearZip Method or until you open another file.  This may improve performance if you plan to do a lot of operations on a particular file, for instance you may need to perform several separate unzips, unzipping one file at a time rather than just filling the FilesList Property with all filenames you wish to unzip.


DoProcessMessages
DoProcessMessages Property

Applies to

TVCLUnZip

Declaration

property DoProcessMessages : Boolean

Description

The DoProcessMessages property determines whether a call to Application.ProcessMessages will be called periodically during operations.  Setting this to true will allow you to cancel long operations by calling the CancelTheOperation Method. It will also allow things like screen repaints and such.


OnStartUnzipInfo
OnStartUnzipInfo Event

Applies to

TVCLUnZip

Declaration

property OnStartUnzipInfo : TStartUnzipInfo

TStartUnzipInfo = procedure( Sender: TObject; NumFiles: Integer; TotalBytes: Comp; var StopNow: Boolean ) of Object;

Description

The OnStartUnzipInfo event handler is executed just before the first file is to be extracted, giving you a chance to abort. NumFiles is the total number of files that is about to be processed.  TotalBytes is the total number of uncompressed bytes that make up the files about to be extracted.  Set StopNow to True if you do not wish continue the operation.


OnFilePercentDone
OnFilePercentDone Event

Applies to

TVCLUnZip

Declaration

property OnFilePercentDone : TFilePercentDone

TFilePercentDone = procedure( Sender: TObject; Percent: LongInt ) of Object;

Description

The OnFilePercentDone event handler is Triggered periodically to report the progress on the current file being processed.  Percent represents a percentage between 1 and 100.


OnTotalPercentDone
OnTotalPercentDone Event

Applies to

TVCLUnZip

Declaration

property OnTotalPercentDone : TTotalPercentDone

TTotalPercentDone = procedure( Sender: TObject; Percent: LongInt ) of Object;

Description

The OnTotalPercentDone event handler is triggered periodically to report the progress of the total bytes of all the files that are being processed.  Percent represents a percentage between 1 and 100.


OnStartUnZip
OnStartUnZip Event

Applies to

TVCLUnZip

Declaration

property OnStartUnZip : TStartUnZipEvent

TStartUnZipEvent = procedure( Sender: TObject; FileIndex: Integer; var FName: String; var Skip: Boolean ) of Object;

Description

The OnStartUnZip event handler is triggered just before a file is about to be extracted.  FName is the complete path and filename of the file that is about to be unzipped.  Notice that it is a VAR parameter.  This allows you to modify the destination and filename of the file just before it is unzipped.  If you do this, be sure it is a complete and valid filename, including the device, path, and filename.  If the destination directory does not exist, then VCLZip will create the complete directory path for you.

If you wish to skip this file altogether (don't unzip it) then just set Skip to True.

NOTE: Prior to VCLZip 2.18, FName was not a VAR parameter and could not be modified.


OnEndUnZip
OnEndUnZip Event

Applies to

TVCLUnZip

Declaration

property OnEndUnZip : TEndUnZipEvent

TEndUnZipEvent = procedure( Sender: TObject; FileIndex: Integer; FName: String ) of Object;

Description

The OnEndUnZip event handler is triggered just after each file has been extracted.  The FName parameter contains the full path to the file that was just unzipped which will allow you to further process this file in any way if you wish.


OnPromptForOverwrite
OnPromptForOverwrite Event

Applies to

TVCLUnZip

Declaration

property OnPromptForOverwrite : TPromptForOverwrite

TPromptForOverwrite = procedure( Sender: TObject; var OverWriteIt: Boolean; FileIndex: Integer; var FName: String ) of Object;

TUZOverwriteMode = (Prompt, Always, Never);

Description

The OnPromptForOverwrite event handler is triggered when the property OverwriteMode is set to Prompt and a file is about to be overwritten.  This gives you a chance to determine whether to overwrite or not.  Set OverWriteIt to True if you wish to overwrite the file, otherwise the file will not be overwritten. You also have the opportunity to rename the file that is about to be unzipped.  If you do this, you should also set OverwriteIt to True.

If this event is not defined and the property OverwriteMode is set to Prompt then the TVCLUnZip component will display a messagebox to ask whether the file that is about to be overwritten, should be overwritten.  In this case you do not get a chance to rename the file.


OnSkippingFile
OnSkippingFile Event

Applies to

TVCLUnZip

Declaration

property OnSkippingFile : TSkippingFile

version 2.15 and earlier:

TSkippingFile = procedure( Sender: TObject; Reason: TSkipReason; FileIndex: Integer ) of Object;

TSkipReason = (srBadPassword, srNoOverwrite);

version 2.16 and later:

TSkippingFile = procedure( Sender: TObject; Reason: TSkipReason; FName: String; FileIndex: Integer ) of Object;

TSkipReason = (srBadPassword, srNoOverwrite, srFileOpenError);

version 2.20 and later:

TSkippingFile = procedure( Sender: TObject; Reason: TSkipReason; FName: String; FileIndex: Integer; Retry: Boolean ) of Object;

TSkipReason = (srBadPassword, srNoOverwrite, srFileOpenError);

Description

The OnSkippingFile event handler is Triggered when a file that would have otherwise been processed is being skipped.

The reason for the file being skipped is in the Reason argument.

FName is name of the file being skipped.

FileIndex is the index into the indexed properties of the archive for the file being skipped (if unzipping), for instance Filename[FileIndex] or CompressedSize[FileIndex].

If this event is called during a zipping process and the reason for skipping is srFileOpenError, setting Retry to True will cause VCLZip to re-attempt to open the file.  This gives you a chance to close the file if it is open by another application and continue zipping, rather than having to start the zipping all over again.  Setting the Retry parameter will be ignored if it is not a zipping situation and if the reason is not srFileOpenError.  See the FileOpenMode property which determines the mode used to open files about to be zipped.

IMPORTANT:   In version 2.16 or later, If FileIndex is -1, this means that this event has been called during a zipping operation. In this case, use the FName parameter only as this reflects a file that is not in the archive, instead FName reflects the name of a file that would have been zipped.  Do not try to use the FileIndex property or an error will occur.

Definition of each reason (TSkipReason) and why OnSkippingFile would be called:

srBadPassword	When unzipping, If an attempt is made to process an encryped file and the Password property does not match the file's password.

srNoOverwrite	When unzipping, If an existing file would be overwritten and the OverWriteMode property is set to either Never, or Prompt and the OnPromptForOverwrite event returned False for the OverWriteIt parameter.

 When zipping, if about to insert a duplicate entry into the archive. (This should happen rarely as conflicts should be taken care of by VCLZip before it reaches this point. Please contact me if this happens)

srFileOpenError	(Version 2.16 or later only) When zipping, if an error occurs opening a file about to be zipped. This will probably mean that the file is locked by another application.  You can set the FileOpenMode property to determine the mode to use to open the file about to be zipped.


OnBadPassword
OnBadPassword Event

Applies to

TVCLUnZip

Declaration

property OnBadPassword : TBadPassword

TBadPassword = procedure( Sender: TObject; FileIndex: Integer; var NewPassword: String ) of Object;

Description

The OnBadPassword event handler is triggered whenever an attempt is made to extract an encrypted file with an incorrect password.  If you wish to RETRY with a new password, then set NewPassword to the desired password.  If you do not set NewPassword to a new password then the file will be skipped, possibly also resulting in a call to the OnSkippingFile Event.


OnBadCRC
OnBadCRC Event

Applies to

TVCLUnZip

Declaration

property OnBadCRC : TBadCRC

TBadCRC = procedure(Sender: TObject; CalcCRC, StoredCRC: LongInt; FileIndex: Integer ) of Object;

Description

The OnBadCRC event handler is triggered when the value for the CRC for a file just extracted does not match the CRC that was calculated by the TVCLUnZip component.   The values for the calculated CRC and the stored CRC are passed in the CalcCRC and StoredCRC variables respectively.


OnInCompleteZip
OnInCompleteZip Event

Applies to

TVCLUnZip

Declaration

property OnInCompleteZip : TInCompleteZip

TIncompleteZip = procedure(Sender: TObject; var IncompleteMode: TIncompleteZipMode ) of Object;

TIncompleteZipMode = (izAssumeMulti, izAssumeBad, izAssumeNotAZip);

Description

The OnInCompleteZip event handler is triggered whenever the component cannot find an END CENTRAL DIRECTORY which means one of the following:

1. This is part of a multi-file zipfile and it is not the last file/disk in the set.

2. It is a bad zip file - corrupted or truncated

3. The file is not a zip file

If VCLZip encounters a file for which it cannot find an end central directory, the behavior depends upon two things:

1. How the IncompleteZipMode Property is set.

2. How you define what happens in the OnIncompleteZip event (if you have one defined that is).

You can set the value for the IncompleteZipMode property in the Object Inspector, anywhere in your code, or inside the OnIncompleteZip event, through the IncompleteMode paratmeter.

>If no OnIncompleteZip event is defined:

If you do not have an OnIncompleteZip event defined, the following happens when VCLZip is presented with a file for which it can't find an end central directory:

IncompleteZipMode Value	Action

izAssumeMulti	An EIncompleteZip exception is thrown.

izAssumeBad	An attempt is made to read as much of the zip file as possible using the local headers.  The results of this can be unpredictable.  If it still can't detect any files in the archive, then an EBadZipFile exception is thrown.

izAssumeNotAZip	An ENotAZipFile exception is thrown.

It is up to your program to trap these exceptions and handle them as you see fit.

>If there IS an OnIncompleteZip event defined:

When no end of central directory is found:

1) The OnIncompleteZip event is called.

2) You have the opportunity to set the IncompleteZipMode property here through the IncompleteMode parameter.

VCLZip's behavior depends on how you set the IncompleteZipMode property.

IncompleteZipMode Value	Action

izAssumeMulti	Another attempt will be made to read the zip file.  It is assumed in this case that you prompted the user for the last disk in a spanned disk set.

izAssumeBad	An attempt is made to read as much of the zip file as possible using the local headers.  The results of this can be unpredictable.  If it still can't read it, then an EBadZipFile exception is thrown.

izAssumeNotAZip	An ENotAZipFile exception exception is thrown.

Again, it is up to your program to trap these exceptions.


OnGetNextDisk
OnGetNextDisk Event

Applies to

TVCLUnZip

Declaration

property OnGetNextDisk : TGetNextDisk

TGetNextDisk = procedure(Sender: TObject; NextDisk: Integer; var FName: String ) of Object;

Description

 NOTE: If you do not define this event then a default OnGetNextDisk is defined that will handle both zipping and unzipping cases.

When Unzipping:

When unzipping from a multi-part zip file this event is triggered when a file that is about to be unzipped is on a different disk from the one that is currently in the drive. NextDisk will tell you the disk number of the multi-part zipfile that should be inserted. The first disk in a disk set is number 1.

If you are working with a multi-file zip (multiple files rather than multiple disks) then you should return the filename of the next file to be processed in the FName parameter.  Setting FName to '' (an empty string) will cancel the zip operation all together.

If you have set the CheckDiskLabels Property to True, then the volume label will be checked for the newly inserted diskette to be sure it is for the next disk in the spanned zip file.  Normal spanned zip files have volume labels like 'PKBACK 001', 'PKBACK 002', etc.  So if the current disk is disk 1, and you have CheckDiskLabels set to True, then OnGetNextDisk will repeat until the correct diskette has been inserted.

When Zipping:

When creating a new multi-part zip file, this event is triggered when the current diskette is full and you should remove it and insert a new diskette.  No checking is involved in this case since VCLZip can only assume you are inserting the disk that you want the next part on, so you may wish to check in some way in this event to be sure that the disk that has been inserted meets your satisfaction.

If you wish to further prepare the diskette that has been inserted (for instance to format or delete currently existing files), you may put code to do so into the OnPrepareNextDisk event.

WARNING!  It is up to you to be sure the user inserted the correct disk.  Results of inserting the wrong disk are unknown and likely not good.

See Also:

OnPrepareNextDisk


Properties
VCLZip Properties

Published:

PackLevel

Recurse

Dispose

StorePaths

StoreVolumes

ZipAction

RootDir

RelativePaths

Store83Names

TempPath

ResetArchiveBitOnZip

SkipIfArchiveBitNotSet

ExcludeList

NoCompressList

AddDirEntriesOnRecurse

PreserveStubs

MultZipInfo Properties

MultiMode

BlockSize

FirstBlockSize

SaveOnFirstDisk

SaveZipInfoOnFirstDisk

CheckDiskLabels

WriteDiskLabels

Public:

IsModified

Inherited from VCLUnZip:

VCLUnZip Properties


PG155
VCLZip Events

OnStartZipInfo

OnStartZip

OnEndZip

OnDeleteEntry

OnDisposeFile

OnNoSuchFile

OnZipComplete

OnUpdate

OnPrepareNextDisk

OnRecursingFile

Inherited from VCLUnZip:

VCLUnZip Events


PG156
 VCLZip Methods

Zip

DeleteEntries

SaveModifiedZipFile

ZipFromStream

ZipFromBuffer Method

FixZip

MakeSFX

MakeNewSFX

SFXToZip


TVCLZip
TVCLZip Component

Properties	Methods	Events

Description

The VCLZip component inherits from TVCLZip and adds capabilites for creating and modifying zip files.  When modifying an existing zip file, all output goes to a temporary file in the Windows temporary directory or, if the TempPath property is defined, output goes to the directory that it specifies.  Once processing is finished, if there were no exceptions, then the original file is deleted and the temporary file replaces it.  If there are any exceptions, then the temporary file is deleted and the original file stays intact.

NOTE:You do not need to use both a VCLUnZip and VCLZip component in order to perform UnZip and Zip operations.  VCLZip alone will handle all zipping and unzipping operations for you.

See TVCLUnZip


Zip
Zip Method

Example

Applies to

TVCLZip

Declaration

function Zip: Integer;

Description

The Zip method compresses files into the zip file specified by the property ZipName.  Prior to calling this method you should add appropriate filenames and wildcards to the FilesList property.  If ZipName is an archive that already exists, the files in FilesList will be added to that archive.  Therefore if the archive already exists and you wish to create a new archive by the same name you will have to delete the original archive first.

 Return Value

The return value is the actual number of files that were added to the zip file.  This may differ from the number of files that you added to the FilesList.  For instance if you added a file to the list that didn't actually exist.  Also, wildcards will normally expand the list to include more files.  If a file is skipped, for instance because there is no such file, then the OnSkippingFile Event will be called, if it has been assigned.


DeleteEntries
DeleteEntries Method

Applies to

TVCLZip

Declaration

function DeleteEntries: Integer;

Description

The DeleteEntries method deletes entries from the zip file specified by the ZipName Property.

Files are deleted in one of two ways:

1) use the Selected property to select the files you wish to delete before calling DeleteEntries.

2) Put filenames and/or wildcard specifications into the FilesList.  Any files within the zip file that match any of the specified files or wildcard masks within the FilesList will be removed from the zip file.

You cannot combine these two methods in one call to DeleteEntries.  If any files have had their Selected property set to True, then the FilesList will be cleared before processing the delete operation.

Return Value

The return value specifies the actual number of entries deleted from the zip file.


PG165
This example shows some modifications being made to the archive and then a call to SaveModifiedZipFile.

begin

...

VCLZip.ZipComment := 'This is a zip comment';

VCLZip.FileComment[0] := 'This is a file comment for the 1st file!';

/* Change all paths and filenames */

for i := 0 to VCLZip.Count-1 do

begin

VCLZip.Pathname[i] := 'backups\mydata\'

VCLZip.Filename[i] := ChangeFileExt( VCLZip.Filename[i], '.BCK' );

end;

VCLZip.SaveModifiedZipFile;

end;


SaveModifiedZipFile
SaveModifiedZipFile Method

Example

Applies to

TVCLZip

Declaration

procedure SaveModifiedZipFile;

Description

The SaveModifiedZipFile method saves a zip file that is currently in the modified state (See the IsModified  Property).  At this time, the actions that will leave a zip file in the modified state are by

•	Adding or modifying a ZipComment Property or any number of FileComments.

•	Writing to any number of Pathname Properties

•	Writing to any number of Filename Properties

Also, anytime that a currently modified zip file is open and the ZipName Property is changed, or the zip file is closed, then the zip file will be saved before continuing.


ZipFromStream
ZipFromStream Method

Applies to

TVCLZip

Declaration

function ZipFromStream( theStream: TStream; FName: String ): Integer;

Description

The ZipFromStream method will take theStream, a TStream or one of it's decendants and zip it to the zip file specified by the ZipName Property.  This allows you to, for instance, take a currently open TFileStream and save it directly to a zip file without having to first save it to a disk file.  All of the VCLZip's current properties will affect the processing of the file.  FName specifies the filename that will be given to the saved file.  If the StorePaths Property is set to True, then path information will be saved if FName includes path information.

Return Value

The return value will be 1 if the stream was zipped and 0 if it was not successfully zipped.


FixZip
FixZip Method

Applies to

TVCLZip

Declaration

function FixZip: Integer;

Description

The FixZip method will attempt to read a zip file that has been truncated and save a complete zip file.  This will save as many compressed files as is possible.

Also, the integrity of each file is tested using the FileIsOK Property, and any files that return False for this property will not be included in the Fixed archive.

Return Value

The return value is the number of compressed file entries in the resulting "fixed" file.


IsModified
IsModified Property

Applies to

TVCLZip

Declaration

property IsModified : Boolean

Description

The IsModified property is True if the current zip file has been modified but not yet saved (See the SaveModifiedZipFile Method).  Currently the only operations that can cause a zip file to be modified without automatically immediately saving the zip file are:

•	Adding or modifying a ZipComment Property or any number of FileComments.

•	Writing to any number of Pathname Properties

•	Writing to any number of Filename Properties


PackLevel
PackLevel Property

Applies to

TVCLZip

Declaration

property PackLevel : Integer

Description

The PackLevel property determines how hard the compression algorighm will try to compress files.  This property can be given a value from 0 through 9.  A value of 0 is no compression at all (STORED) which is useful for adding things like other zip files (which will compress very little if any) to an archive.  A value of 1 will compress the fastest, but the compression ratio will be the lowest.  A value of 9 will compress the slowest, but the compression ratio will be the highest.

You may specify particular files that you do not want VCLZip to try to compress by adding their filespecs or wildcards to the NoCompressList.


Recurse
Recurse Property

Applies to

TVCLZip

Declaration

property Recurse : Boolean

Description

The Recurse property determines whether subdirectories will be recursed to look for files to be compressed when zipping with a wildcard mask.  Set to true if you wish subdirectories to be traversed.

If this value is set to True, and a wildcard mask is specified in the FilesList without any path information, then the value of the RootDir Property will determine which directory zipping will start in.  Results may be unexpected or even bad if you do not supply path information either in the FilesList or the RootDir Property.

NOTE:  Overriding the Recurse Propery

By adding the following characters to the beginning of the filenames being added to the FilesList, you can override whatever the current setting is for the RECURSE property:

'>' will force recursion into subdirectories '|' will force NO-recursion

For instance:

VCLZip1.FilesList.add('>c:\windows\*.ini');

will get all .ini files in and below the windows directory reguardless of what the recurse property setting is.

and:

VCLZip1.FilesList.add('|c:\windows\sys*\*.dll');

will get all .dll files in subdirectories of the windows directories that start with 'sys' but will not recurse into any directories below the sys* directories.

It is important to note that this is only useful for zipping, not unzipping operations.


Dispose
Dispose Property

Applies to

TVCLZip

Declaration

property Dispose : Boolean

Description

The Dispose property, if set to True, will cause the original disk files that were added to the zip file to be deleted from the disk, in effect, moving the files into the zip file. USE THIS OPTION WITH EXTREME CAUTION. If an exception occurs during processing, files will not be deleted.


PG212
 StoreVolumes

RelativePaths

Recurse


StorePaths
StorePaths Property

See also

Applies to

TVCLZip

Declaration

property StorePaths : Boolean

Description

The StorePaths property, if set to True, will cause path information to be stored with the zip entry. If the StoreVolumes Property is set to True then the entire path will be stored.  If the StoreVolumes Property is False, then only the path information will be stored.

If StorePaths is False, then only the filename itself is stored.

Note that if the RelativePaths Property is set to True, then this StorePaths property will automatically be set to True also.  Likewise, if the StorePaths property is ever set to False, then both the RelativePaths and the StoreVolumes Property will automatically be set to False.

The following shows the results, assuming StorePaths is True:

StoreVolumes                Filename                                         Stored Result

True                     C:\DIRECTORY\FILENAME.EXT        C:\DIRECTORY\FILENAME.EXT

False                   C:\DIRECTORY\FILENAME.EXT        DIRECTORY\FILENAME.EXT

The RelativePaths Property will also affect what is stored for the path information.


StoreVolumes
StoreVolumes Property

Applies to

TVCLZip

Declaration

property StoreVolumes : Boolean

Description

The StoreVolumes property determines whether volume information is stored along with the filename within the zip file when files are zipped.  This is useful when making backups into a zip file when the files are from different volumes.  It will make it easier to restore files later, or to make new backup zip files based on the same zip file entries.  Volume information (i.e. C:\) will be saved if this property is set to True.

IMPORTANT!!!: Setting this property to True will cause the resulting archive to NOT be PKZip compatible.  This is the only property which will have this effect. While VCLZip will be able to correctly unzip files that have volume information stored, other zip utilities and components most likely will have problems with it.  So, if you wish to maintain complete PKZip compatibility, please do not use this property!


ZipAction
ZipAction Property

Applies to

TVCLZip

Declaration

property ZipAction : TZipAction

TZipAction = (zaUpdate, zaReplace, zaFreshen);

Description

The ZipAction property determines whether files will be replaced in a zip or not.  If ZipAction is set to zaUpdate then a zip entry will only be replaced if the disk file is newer than the zip entry.  If ZipAction is set to zaReplace, then the zip entry will be replaced by the disk file regardless of the file dates.  A ZipAction of zaFreshen is the same as zaUpdate, except that filenames that do not match any entries already in the zip file will be ignored and not added to the zip.

IMPORTANT: When replacing files in an already existing archive, matching files on your hard drive with what is in the archive is dependant on how the StorePaths Property and the RelativePaths Property are set.  These properties should be set exactly the same as they were when the archive was originally created. The reason for this is that path information is used when comparing a file that is being zipped to the files that are already in the archive.

Also, be sure to include kpZipObj in your USES list when using this property.


RootDir
RootDir and RelativePaths Examples

 With VCLZip1 do

begin

ZipName := 'C:\BACKUP.ZIP';

RootDir := 'C:\MYFILES';    /* work from this directory */

FilesList.Add('*.PAS');        /* zip all PAS files */

FilesList.Add('*.DFM');       /* zip all Form files */

Recurse := True;

StorePaths := True;

Zip;

end;

Note that the same thing could be accomplished by including the path with the filenames as in the following:

 With VCLZip1 do

begin

ZipName := 'C:\BACKUP.ZIP';

FilesList.Add('C:\MYFILES\*.PAS');        /* zip all PAS files */

FilesList.Add('C:\MYFILES\*.DFM');       /* zip all Form files */

Recurse := True;

StorePaths := True;

Zip;

end;

If you want to store relative path information using the RelativePaths Property, then you MUST use the RootDir property to specify the directory in which to begin recursing subdirectories.

 With VCLZip1 do

begin

ZipName := 'C:\BACKUP.ZIP';

RootDir := 'C:\MYFILES';    /* work from this directory */

FilesList.Add('*.PAS');        /* zip all PAS files */

FilesList.Add('*.DFM');       /* zip all Form files */

RelativePaths := True;       /* this automatically sets StorePaths and Recurse to True also */

Zip;

end;


RootDir
RootDir Property

Example

Applies to

TVCLZip and TVCLUnZip

Declaration

property RootDir : String

Description

When Zipping:

The RootDir property determines where zipping will start for any wildcard entries or filenames in the FilesList Property that do not already include path information.  Essentially, the value of RootDir will be prepended to anything in the FilesList that does not have any path information when zipping.

Also, when storing relative path information using the RelativePaths Property, you must use this RootDir property to specify the directory from where path information will begin being saved.  See RelativePaths for more information on this topic.  Essentially the value of RootDir will be stripped from the saved path information in this case.

When UnZipping:

Using the RootDir when unzipping allows you to extract files from an archive that was not created using the relative paths option and still treat it as though it was.  In this case you should set RootDir to the value that you want stripped from the internal path information for each file that is unzipped.  For instance, if you had an archive containing the following information:

Filename	Path Info

file1.txt	backups\subdir1\

file2.txt	backups\subdir1\subdir2\

file3.txt	backups\subdir1\subdir3\

and you wished to extract these files to a DestDir of c:\restore\backups and retain the directory structure, normally you would end up with something like the following being extracted:

c:\restore\backups\backups\subdir1\file1.txt

c:\restore\backups\backups\subdir1\subdir2\file2.txt

c:\restore\backups\backups\subdir1\subdir3\file3.txt

when what you really wanted was:

c:\restore\backups\subdir1\file1.txt

c:\restore\backups\subdir1\subdir2\file2.txt

c:\restore\backups\subdir1\subdir3\file3.txt

You can produce the desired results simply by setting

RootDir := 'backups\subdir1\';

before extracting.  What this does is effectively strip 'backups\subdir1\' from the internal path information of each file prior to extracting.  Remember that you should set RootDir according to how the path information is stored in the archive.  Do not begin it with a '\' character and if the path information includes disk information then you should include that also.

Note that if RootDir is not a substring of the internal path information then this action will not happen.


BlockSize
BlockSize Property

Example

Applies to

TVCLZip

Declaration

property MultiZipInfo.BlockSize : LongInt

Description

The BlockSize property determines the size of each file that is created as a part of a Blocked Zip File.


PG227
Creating Spanned Disk Zip Files

Creating Blocked Zip Files

MultZipInfo Properties


MultiMode
MultiMode Property

See also	Example1	Example2

Applies to

TVCLZip and TVCLUnZip

Declaration

In TVCLUnZip and TVCLZip:

property MultiMode : TMultiMode

In TVCLZip:

property MultiZipInfo.MultiMode : TMultiMode

TMultiMode = (mmNone, mmSpan, mmBlocks);

Description

The MultiMode property determines whether a multi-part zip file will be created as several files on the same disk or a a zip file that actually spans physical disks.

Value	Meaning

mmNone	Normal zip files

mmSpan	Zip file will physically span disks (if large enough)

mmBlocks	Zip file will be broken into separate files (blocks) on the same disk (typically to be copied to separate disks later).

When using the VCLUnZip component you should set this property as follows:

UnZipper.MultiMode := mmNone;

When using the VCLZip component, you may set or read this property the same way, or you may access it through the MultZipInfo Property as follows:

Zipper.MultiZipInfo.MultiMode := mmBlocks;

When opening a zip file, (that is after calling the ReadZip Method) if a multi-file zip file is detected, this property is automatically set according to what type of media the zip file is on.  If the zip file is on a REMOVABLE disk, the multi-file zip is considered to be a Spanned Disk Set with each file residing on a separate removable disk.  Therefore the MultiMode property is set to mmSpan.  If, however, the zip file is NOT on a REMOVABLE disk, it is considered to be a Blocked Zip File and this property is set to mmBlocks.

After opening the zip file, you may modify this property if the automatic detection is not correct.


OnStartZip
OnStartZip Event

Applies to

TVCLZip

Declaration

property OnStartZip : TStartZipEvent

TStartZipEvent = procedure( Sender: TObject; FName: String; var ZipHeader: TZipHeaderInfo; var Skip: Boolean ) of Object;

Description

The OnStartZip event handler is executed when a file is about to be compressed.  This gives you a chance to convey information to the user, skip this particular file, or even modify some of the information that is stored along with it in the archive.

IMPORTANT: Be sure to include kpZipObj in your USES list if you plan on using this event!  It has the required definition of the ZipHeaderInfo object.

Parameters

FName: The filename of the file about to be compressed including the full path.

Skip:  Set this to True if you do not wish to compress this file.  This is useful if you want to avoid zipping certain files. Say for instance you don't want to zip files with the extention '.TMP'.  You could check FName to see if it's extention is '.TMP' and if so, set Skip to True.  No '.TMP' files will be zipped.

ZipHeader: This object contains all of the information for this file that will go into the archive.  You may change this information but you must be careful because you could corrupt the archive if you try to do things that you shouldn't. If you stick to changing only the following information you will be safe:

ZipHeader.Filename	Change this file's Filename (in the archive)

ZipHeader.Pathname	Change this file's path information

ZipHeader.SetDateTime( DateTime: TDateTime )	Change the timestamp for this file

ZipHeader.SetNewFileComment( NewComment: String )	Add a comment for this file

For example in your OnStartZip event you may wish to do something like the following:

procedure MyForm.OnStartZip( Sender: TObject; FName: String;  var ZipHeader: TZipHeaderInfo; var Skip: Boolean );

begin

If UpperCase(ExtractFileExt(FName)) = '.DLL' then	/* Do only to DLL files*/

begin

ChangeFileExt( Zipper.filename, '.DL_');	/* Change the extention*/

ZipHeader.SetDateTime( Now );	/* Set the time to current time */

ZipHeader.Pathname := 'DEFAULT\DLL';	/*  DLL's go into the DLL dir*/

ZipHeader.SetNewFileComment( 'This is a DLL' );	/* Create a comment for DLL's*/

end;

end;


OnDisposeFile
OnDisposeFile Event

Applies to

TVCLZip

Declaration

property OnDisposeFile : TDisposeEvent

TDisposeEvent = procedure( Sender: TObject; FName: String; Skip: Boolean ) of Object;

Description

The OnDisposeFile event handler is executed for each file, just before it is about to be deleted from disk. This will only happen if you have set the Dispose Property to True causing each file that has been compressed to be deleted from disk, effectively "moving" the files from disk into the zip file.  No files are actually deleted until the zip file has been successfully created.


Registration
Registering VCLZip

The price for the VCLZip component is $49.95 PER DEVELOPER.  There are no royalty fees.  You may not resell VCLZip or VCLUnZip as a Zip or UnZip component nor may you use VCLZip or VCLUnZip to create and sell a zip/unzip component. You may not redistribute the source code or the VCLZip or VCLUnZip DCU files (It must be compiled into your executable application).  If you would like to work out some other form of registration such as a site license or corporate license, please email me.

The most up-to-date information can always be found on the KpGb Software web site at:

http://www.bigfoot.com/~boylank

Paying with a check or Cash

You may register directly with me if you are able to send a $US check.  If you would like to register in this way, please send me an email message (boylank@bigfoot.com) in order to receive instructions on doing so. Once I receive the check, I will email the source code to you.

You may also pay with wire transfer, $US check, EuroCheque, or cash to Shareit. See Registering via the Internet below for more details.

Registering via the Internet

You may register VCLZip online on the Internet at http://www.shareit.com/programs/100391.htm. Alternatively, you can go to http://www.shareit.com and enter the program number there: 100391.

If you do not have access to the Internet, you can register via phone, fax or postal mail. Please print out the following form, and fax or mail it to:

Europe:

element 5 AG

ShareIt!

Habsburgerring 3

50674 Koeln

Germany

Phone: 0221-2407279

Fax: 0221-2407278

E-Mail:         register@shareit.com

USA:

If you are located in the USA, you can also order by phone, and pay by sending a check or cash to the following address:

ShareIt! Inc.

PO Box 844

Greensburg, PA 15601-0844

Phone (orders only): 1-800-903-4152

Phone (customer support): 724-850-8186

Fax: 724-850-8187

(Please send only checks drawn by US-American banks to this address.)"

Registration form for VCLZip

Program No.: 100391.htm

Last name: ___________________________________

First name: ____________________________________

Company: ____________________________________

Street and #: ______________________________________

City, State, postal code: ________________________________

Country: _______________________________________

Phone: _____________________________________

Fax: ________________________________________

E-Mail: ______________________________________

How would like to receive the registration key/full version?

e-mail 	- fax	- postal mail

How would you like to pay the registration fee of $49.95:

credit card - wire transfer - EuroCheque - cash

Credit card information (if applicable)

Credit card: Visa - Eurocard/Mastercard - American Express - Diners Club

Card holder: ________________________________

Card No.: ___________________________________

Date of Expiration : ___________________________________

Date / Signature ___________________________

After registering, you will receive  the source code.  You will receive the source code via email if you register electronically. Along with the source code you will also receive instructions on how to install the component using the source code.  Installing with the source code will eliminate the restriction of being able to only use VCLZip while the Delphi IDE is running.  Registering means you will receive point releases at no charge.  You will also be put on a mailing list and recieve information on all future upgrades/point releases.

If you need more information on registering, please email me at boylank@bigfoot.com.

VCLZip Delphi Component - Copyright 1997, Kevin L. Boylan


Installation
Installing VCLZip and its Help Files

Default Installation Directory Structure

C:\VCLZip

Downloaded in kpDemosd.exe:	Delphi example projects

\Examples	Contains example directories

\Examples\ZipUtil	Complete Zip Utility Example Form Files

\Examples\ZipUtil\Proj_32	DPR and RES files for D2, D3 and D4

\Examples\ZipUtil\Proj_16	DPR and RES files for D1

\Examples\Streams	Small example showing stream zipping

\Examples\Streams\Proj_32	DPR and RES files for D2, D3 and D4, and sfx stubs

\Examples\Streams\Proj_16	DPR and RES files for D1, and sfx stubs

Downloaded in kpDemosc.exe:	BCB example projects

\Examples\BCB\ZipUtil	Complete Zip Utility Example Form Files

\Examples\BCB\ZipUtil\CB3	BCB3 Project files

\Examples\BCB\ZipUtil\CB4	BCB4 Project files

Downloaded in Helpfile.zip:

\Help	Help Files (.hlp, .kwf, .cnt)

Downloaded in kpXXX_DX.exe:

\DelphiX	DCU's for the particular version of VCLZip and Delphi you are evaluating

\DelphiX\SFX	a 16bit and a 32bit SFX Stub

\DelphiX\Help	Help Files (.hlp, .kwf, .cnt)

Downloaded in kpXXX_BX.exe:

\BCBX	OBJ's for the particular version of VCLZip and C++Builder you are evaluating

\BCBX\SFX	a 16bit and a 32bit SFX Stub

\BCBX\Help	Help Files (.hlp, .kwf, .cnt)

If you downloaded the evaluation version it will be for a specific version of Delphi or BCB.  If you are installing the registered source code, you need the password and you will have the option of installing for 16 bit (Delphi) or 32 bit Delphi/BCB.  You may always run the installation again to install for a different version of Delphi/BCB.

Installing the Evaluation Components

Please see the INSTALL.TXT file that was installed  into the same directory as the DCU or OBJ files for correct installation instructions.

Installing the Component's Help

Delphi 1 and 2:

Move the VCLZIP.HLP file from your component directory to your DELPHI\BIN directory.  Move the VCLZIP.KWF file to your DELPHI\HELP directory.  Now run the HELPINST.EXE (either double click from File Manager in the HELP directory or from the icon in Program Manager.   Now, while in HELPINST, click the open file toolbar button and find and select the DELPHI.HDX file in the DELPHI\BIN directory.  Then click the '+' toolbar button and find and select the VCLZIP.KWF file in the DELPHI\HELP directory.  This will add the VCLZIP.KWF file to the listbox that you can see.  Now click the 'Save' toolbar button and the VCLZIP help file will be registered with Delphi.  You may now exit.

Delphi 3 and 4:

Move the VCLZIP.HLP and VCLZIP.CNT file to your DELPHI\HELP directory.  In Dephi 3 for example, edit the DELPHI3.CFG file by adding a link to the 3rd party section at the bottom.  Add a line that looks like:

:Link vclzip.hlp

Then edit the DELPHI3.CNT file by adding a line at the bottom that looks like:

:Include vclzip.cnt

Installing the HELP files in this way will allow you to get context sensitive help on each property and event by pressing F1 while a particular property or event is selected in the Object Inspector.

Delphi 5

Copy the VCLZIP.HLP and VCLZIP.CNT file to the Delphi \Help directory.

Select Help | Customize from the D5 menu.

In the Contents page (optional) click "Add Files", change type to .CNT file and add in the VCLZIP.CNT file.

On the Index and Link pages click "Add Files", add the VCLZIP.HLP file.

Be sure to click "Save Project" before exiting the OpenHelp utility.


OnStartZipInfo
OnStartZipInfo Event

Applies to

TVCLZip

Declaration

property OnStartZipInfo : TStartZipInfoEvent

TStartZipInfo = procedure( Sender: TObject; NumFiles: Integer; TotalBytes: Comp; var EndCentralRecord: TEndCentral; var StopNow: Boolean ) of Object;

Description

The OnStartZipInfo event handler is executed just before the first file of an archive is to be zipped, giving you a chance to abort.  You also receive useful information as well as the chance to add a zip comment at the time of creating the zip file.

IMPORTANT: Be sure to include kpZipObj in your USES list if you plan on using this event!  It has the required definition of the TEndCentral object.

The paramaters are:

NumFiles	Total number of files that is about to be processed.  This may not be the actual number of files that ends up getting zipped for various reasons.  Check the return value of the Zip Method for the actual number of files that finally get zipped.

TotalBytes	Total number of uncompressed bytes that make up all of the files about to be zipped.

StopNow	Set this to True if you do not wish continue the zip operation.

EndCentralRecord	Use this to add a zip comment as follows:

EndCentral.SetNewZipComment( 'This is a ZipComment' );


OnEndZip
OnEndZip Event

Applies to

TVCLZip

Declaration

property OnEndZip : TEndZipFileEvent

TEndZipFileEvent = procedure( Sender: TObject; FName: String; UncompressedSize, CompressedSize, CurrentZipSize: LongInt ) of Object;

Description

The OnEndZip event handler is triggered just after each file has been compressed.

Parameters

FName = the filename of the file that was just compressed.

UnCompressedSize = the normal size of the file that was just compressed.

CompressedSize = the size of the compressed entry in the zip file.

CurrentZipSize = the size of the zip file right after this file was added.


OnDeleteEntry
OnDeleteEntry Event

Applies to

TVCLZip

Declaration

property OnDeleteEntry : TDeleteEvent

TDeleteEvent = procedure( Sender: TObject; FName: String ; Skip: Boolean ) of Object;

Description

The OnDeleteEntry event handler is triggered just before a zip entry is about to be deleted from the zip file.

Parameters

FName = the filename of the file that is about to be deleted.

Skip = Set this to True if you do not wish this file to be deleted.


OnNoSuchFile Event

Applies to

TVCLZip

Declaration

property OnNoSuchFile : TNoSuchFileEvent;

TNoSuchFileEvent = procedure( Sender: TObject; FName: String ) of Object;

Description

The OnNoSuchFile event handler is triggered when you have entered a file into the FilesList Property zipped and there is no such file.

Parameters

FName = the filename of the file that was added to the FilesList that does not exist.


ExternalFileAttributes
ExternalFileAttributes Property

Applies to

TVCLUnZip

Declaration

property ExternalFileAttributes[ Index ]: LongInt

Description

The ExternalFileAttributes property contains the MSDOS file attributes in the low order byte.  You can read this using the file attribute constants faReadOnly, faDirectory, faArchive, faHidden, faSysFile, and faVolumeID.


PG313
ExternalFileAttributes

ResetArchiveBitOnZip

RetainAttributes

SkipIfArchiveBitNotSet


RetainAttributes
RetainAttributes Property

See also

Applies to

TVCLUnZip

Declaration

property RetainAttributes: Boolean

Description

The RetainAttributes property should be set to true if you wish unzipped files to retain the attributes that they had when they were originally zipped.


Spanning
Creating Spanned Disk Zip Files

Spanned zip files are single zip files that span across multiple disks.   This allows you to backup more files than would otherwise fit onto a single disktette.  To create a spanned disk set do the following:

•	Define an OnGetNextDisk event that will allow the disk to be swapped. (Note that beginning with version 2.17, this step is optional.  If you do not provide an OnGetNextDisk event, then a default one is provided for you)

•	Set the ZipName Property to a path and filename that is on a removable disk such as 'A:\BACKUP.ZIP'.

•	Set the MultiMode Property to mmSpan

•	If you want VCLZip to write labels on the disks, like PKZIP does, then set the MultiZipInfo.WriteDiskLabels property to True.  The first disk will contain the label PKBACK# 001, the second will contain PKBACK# 002, and so on.

•	Specify the files you want zipped by adding filespecs and/or wildcards to the FilesList Property.

•	Call the Zip Method.

 IMPORTANT:   Normally, PKZip compatible spanned zip files require that the LAST disk of the disk set be inserted first in order to open up the zip file.  This often creates confusion and is an annoyance.  VCLZip has the unique capability to create and read spanned zip files which will allow VCLZip to open a spanned zip file from the first disk.  This option does not cause the spanned zip file to be non-PKZip compatible as PKZip, WinZip, and all of the other zip utilities can still open and read the spanned zip file normally.  However, VCLZip will, if this option is set to True, write some extra information onto the first disk in a separate file.  VCLZip will detect this file if the first disk is inserted first, and read from it, the information it would otherwise need the last disk to obtain.  For further information see SaveZipInfoOnFirstDisk.

Example:  First, define your OnGetNextDisk procedure that allows the disk to be swapped. (Note that beginning with version 2.17, this step is optional.  If you do not provide an OnGetNextDisk event, then a default one is provided for you)...

procedure TVCLZipForm.ZipperGetNextDisk(Sender: TObject;  NextDisk: Integer; var FName: String);

var

MsgArray: String;

begin

Screen.Cursor := crDefault;

MsgArray := 'Please insert disk ' + IntToStr(NextDisk) + ' of the multi-disk set.';

If MessageDlg(MsgArray,mtConfirmation,[mbOK,mbCancel],0) = mrCancel then

FName := '';  /* Set FName to '' to cancel */

Screen.Cursor := crHourGlass;

end

And in your code that does the zipping...

With VCLZip1 do

begin

ZipName := 'A:\BACKUP.ZIP';

MultiZipInfo.MultiMode := mmSpan;   /* Set to span disks */

MultiZipInfo.WriteDiskLabels := True;   /*Actually this is the default*/

MultiZipInfo.SaveOnFirstDisk := 200000;  /* Optional to save room on first disk */

FilesList.Add('C:\MYFILES\*.*');

Recurse := True;   /* Recurse directories */

Zip;

end;

And that's it!  Each disk will be filled with a zip file part.  Each disk will contain a file by the same name, in the example above, each disk will contain a file called BACKUP.ZIP.  The file will take up as much room as is available on each disk. So, if you would like other files to be on any of the disks, be sure to put them there first.

Also note that a spanned disk set can be created by copying individual files from a  Blocked Zip File, each to a separate diskette.


MultiZipInfo
MultZipInfo Properties

Applies to

TVCLZip

The TMultiZipInfo Property contains most of the properties that deal with Spanned and Multi-File zip files.  It contains the following properties:

CheckDiskLabels

WriteDiskLabels

MultiMode

BlockSize

FirstBlockSize

SaveOnFirstDisk

SaveZipInfoOnFirstDisk


FirstBlockSize
FirstBlockSize Property

See also	Example

Applies to

TVCLZip

Declaration

property MultiZipInfo.FirstBlockSize : LongInt

Description

The FirstBlockSize property determines the size of the FIRST file that is created as a part of a  Blocked Zip File. Each file after that is created according to the BlockSize Property.  You may wish to make FirstBlockSize smaller than BlockSize, for instance, if you want to leave room on a first disk of an installation disk set for installation files.


PG703
TMultZipInfo Properties BlockSize Property


WriteDiskLabels
WriteDiskLabels Property

See also	Example

Applies to

TVCLZip

Declaration

property WriteDiskLabels: Bolean;

Description

If set to True, the VCLZip component will write volume labels on each disk of a Spanned Disk Set.  These labels will be created just as PKZip would create them.  The first label will be PKBACK# 001, the second will be PKBACK# 002 and so on.


CheckDiskLabels
CheckDiskLabels Property

See also

Applies to

TVCLZip and TVCLUnZip

Declaration

In TVCLUnZip and TVCLZip:

property CheckDiskLabels: Boolean;

In TVCLZip:

property MultiFileInfo.CheckDiskLabels: Boolean;

Description

If set to True, the VCLUnZip component will check volume labels on Spanned Disk Sets each time a new disk is inserted.  If the volume label does not match the disk number that is requested, the request will be repeated until the proper disk is inserted.

If set to False, the volume labels will be ignored.  It will then be up to you to be sure the correct disk is inserted.  Also note that if a spanned disk set was created by VCLZip while the WriteDiskLabels property is False, then there will be no labels to check.  However, a spanned disk set that is expected to be read by PKZip, or another zip utility should have the labels.

IMPORTANT:

This is a PUBLIC property in the VCLUnZip component, but it is a PUBLISHED subproperty of the TMultZipInfo Property in the VCLZip property.

When only using the VCLUnZip component, set this property as follows...

UnZipper.CheckDiskLabels := True;

You may set this property in VCLZip the same way, or you may set it through the MultiZipInfo property, such as...

Zipper.MultiZipInfo.CheckDiskLabels := True;


Blocked Zip Files
Creating Blocked Zip Files

Blocked zip files are spanned zip file images that are created in specific sized physical blocks directly to the hard drive.   This allows you to create spanned zip files without actually creating them directly to diskettes first.   This may be useful, for instance, if you are creating a master installation disk set that will be copied to diskettes many times.  The result of a Blocked zip file will be a series of files, the first with an extention of '.001', the second with an extention of '.002' and so on. So if you specified a ZipName of 'BACKUP.ZIP', the result will be 'BACKUP.001' ... 'BACKUP.nnn'.  These files are structurally the same as a Spanned Disk Set only all files are created in one destination directory instead of to separate disks.

Create a Blocked Zip File by following these steps:

•	Set the ZipName Property to a path and filename in a directory with enough room to hold the entire backup.

•	Set the MultiMode Property to mmBlocks

•	Set the FirstBlockSize Property to the size you want the first file to be in bytes.

•	Set the BlockSize Property to the size you want all other blocks to be in bytes.

•	Specify the files you want zipped by adding filespecs and/or wildcards to the FilesList Property.

•	Call the Zip Method.

Example:

 With VCLZip1 do

begin

ZipName := 'C:\SOMEDIR\BACKUP.ZIP';

MultiZipInfo.MultiMode := mmBlocks;

MultiZipInfo.FirstBlockSize := 700000; /*approximately 1/2 diskette*/

MultiZipInfo.BlockSize := 1457600;     /*entire diskette*/

FilesList.Add('C:\MYFILES\*.*');

Recurse := True;   /* Recurse directories*/

Zip;

end;

All of the files will be created automatically.  There is no need to insert new disks for this operation.

When transferring Blocked Zip files onto disks, if you wish to make a standard pkzip compatible spanned disk set, be sure:

1) You should give each file the .ZIP extention on the disks.

2) The component (or any unzip utility) expects to find the correct disk label on each disk. For example, Disk 1 should be labeled as PKBACK# 001, Disk 2 should be labeled PKBACK# 002, etc.  If the disk label is not what the component expects, the component will not operate correctly, unless...

Set the CheckDiskLabels Property to false if you do not want the component to check the disk labels when unzipping spanned disk sets.  You must make sure your program asks for the correct disk and has a way of verifying the correct disk number.

However, you can copy the blocked segments to diskettes "as they are" and still work with them with VCLZip. However, other zip utilities won't likely be able to work with them.  When unzipping, you  will still need to insert the last disk first (just as with a normal zip file).  What you will have to do differently is:

1) Definitely set the CheckDiskLabels Property to False.

2) Be sure to define your own OnGetNextDisk Event.  Notice that this event passes in a filename through the FName parameter.  You should simply change the extention on this filename to match the number that is passed in through the NextDisk parameter so that it matches the ".001", ".002", etc extention that is described above, by using a statement something like the following:

     FName := ChangeFileExt(FName, '.'+Format('%3.3d',[NextDisk]));

You can also check for the existence of the new filename in order to be sure that the proper disk has been inserted.


PG86
Creating a Zip File

UnZipping Files

Creating Spanned Disk Zip Files

Creating Blocked Zip Files

Using Streams

Creating a Self Extracting Zip File

Streamlining Your Application

Frequently Asked Questions

Acknowledgments


Creating Zip Files
Creating a Zip File

Creating a new zip file is very easy with VCLZip.  Just follow these steps:

•	Set the ZipName Property to a new filename.  It's best to include a full path!

•	Add any filespecs or wildcards to the FilesList Property that you wish to be zipped.

•	Set any other options that you want.

•	Call the Zip Method

And that's it!!!  Here's an example:

 With VCLZip1 do

begin

ZipName := 'C:\BACKUP.ZIP';

FilesList.Add('C:\MYFILES\*.PAS');	/* Zip all .PAS files */

Recurse := True;	/* Recurse directories */

StorePaths := True;	/* Keep path information */

PackLevel := 9;	/* Highest level of compression */

NumberZipped := Zip;	/* Return value of Zip is the actual number of files zipped */

end;

Be sure to include kpZipObj in your USES list if you set properties like OverwriteMode.  kpZipObj includes many definitions that you may use.


Streams
Using Streams

See Also

Zipping and UnZipping to and from streams is as easy as zipping to and from zip files.  This allows your application to read from and save directly to streams as if they were normal files.  You still have full control over all options like encryption, compression level, etc.

The following example can be found with the Demo distribution as a Delphi example project.  Notice that, while it initially reads a disk based zip file into a TMemoryStream, it performs memory to memory zipping and unzipping.  Furthermore, you can create a new zip file directly to memory by pointing the ArchiveStream Property at a newly created, empty TMemoryStream.

procedure TForm1.OnOpenClick(Sender: TObject);

var

TxtStream: TMemoryStream;

n: Integer;

begin

FileDialog.FileBox.Clear;

For n := 0 to Zipper.Count-1 do

FileDialog.FileBox.Items.Add( Zipper.Fullname[n] );

FileDialog.SelectedFile.ReadOnly := True;

FileDialog.ShowModal;

With FileDialog do

If (ModalResult = mrOK) and (SelectedFile.Text <> '') then

begin

CurrentFile := SelectedFile.Text;

TxtStream := TMemoryStream.Create;

n := Zipper.UnZipToStream( TxtStream, CurrentFile );

If n > 0 then

begin

TxtStream.Position := 0;

TextMemo.Lines.Clear;

TextMemo.Lines.LoadFromStream( TxtStream );

end;

TxtStream.Free;

Form1.Caption := CurrentFile;

end;

end;

procedure TForm1.OnSaveClick(Sender: TObject);

var

TxtStream: TMemoryStream;

n: Integer;

i: LongInt;

begin

If TextMemo.Modified then

With FileDialog do

begin

FileBox.Clear;

For n := 0 to Zipper.Count-1 do

FileBox.Items.Add( Zipper.Fullname[n] );

SelectedFile.ReadOnly := False;

SelectedFile.Text := CurrentFile;

ShowModal;

If ModalResult = mrOK then

begin

CurrentFile := SelectedFile.Text;

TxtStream := TMemoryStream.Create;

TextMemo.Lines.SaveToStream(TxtStream);

i := TxtStream.Size;

TxtStream.Position := 0;

/* Update the modified file */

n := Zipper.ZipFromStream( TxtStream, CurrentFile );

TxtStream.Free;

TextMemo.Modified := False;

Form1.Caption := CurrentFile;

end;

end;

end;

procedure TForm1.FormCreate(Sender: TObject);

var

zipfile: TFileStream;

begin

/* This shows zipping and unzipping from stream to stream */

zipfile := TFileStream.Create( ExtractFilePath(Application.ExeName)+'Demo.Zip', fmOpenRead );

/* Read the disk archive into a memory stream and work with it there */

Zipper.ArchiveStream := TMemoryStream.Create;

Zipper.ArchiveStream.CopyFrom( zipfile, zipfile.Size );

zipfile.Free;

Zipper.PackLevel := 9;

Zipper.ReadZip;

end;

procedure TForm1.FormClose(Sender: TObject; var Action: TCloseAction);

var

zipfile: TFileStream;

begin

zipfile := TFileStream.Create( ExtractFilePath(Application.ExeName)+'Demo.Zip', fmOpenWrite );

/* Save the memory stream as a disk file now */

Zipper.ArchiveStream.Position := 0;

zipfile.CopyFrom( Zipper.ArchiveStream, Zipper.ArchiveStream.Size );

zipfile.Free;

Action := caFree

end;

procedure TForm1.Close1Click(Sender: TObject);

begin

If TextMemo.Modified then

OnSaveClick(Self);

end;


Streamlining
Streamlining Your Application

If there are certain features of VCLZip/VCLUnZip that you know you don't need, it is possible to "streamline" things a little by removing support for some features and thereby removing the code and data that supports those features from your executable.  The table below shows you which conditionals to define in the project options dialog box in order to remove particular features:

Define Conditional	If you don't need support for

NOLONGNAMES	long filenames in Delphi 1

NODISKUTILS	verifying disk labels on spanned disk sets in Delphi 1

NOSTREAMBUFF	the additional speed of buffered file i/o

INFLATE_ONLY	earlier versions of PKZip decompression

By defining MAKESMALL you can reduce the size of you application dramatically.  This removes all dependencies on the Dialogs, Forms, Controls, and FileCtrl units, which results in a smaller footprint.  This can be quite useful when putting VCLZip into a DLL for instance.  In order to make this work, go into your Project | Options and select the Directories/Conditionals tab and enter MAKESMALL in the conditional defines text box.  In Delphi you can add this conditinal define to the project options of your application that uses VCLZip and then do a "build all".  In BCB you will have to add this to the project options of the package that contains VCLZip and then rebuild the package.

If you define MAKESMALL, the only things you lose are:

a) ZIP file open dialog box that appears when the ZipName is set to "?"

b) Select Directory dialog box that appears when the DestDir is set to "?"

c) Changing the cursor to an hour glass during some operations.

d) No long filename support in Delphi 1. (NOLONGNAMES is automatically defined)

e) No creating disk labels in Delphi 1 when creating disk spanned archives

By defining NO_RES, this avoids using the .RES file that contains strings that are used within VCLZip for things like MessageBox messages.  Your strings will instead be compiled directly into the code.  This will ofcourse make it more difficult to internationalize you code and may result in poorer memory use, so you will most likely not want to define NO_RES.

By defining the conditional ASSERTS, in either Delphi 1 or Delphi 2, or by selecting the Asserts compiler option in Delphi 3, or 4, or BCB, you will turn on some assert statements that have been added to the compression process.  In general you should never need these so you should be sure this isn't defined in order to maximize speed.

Also, for speed purposes, be sure to turn off all error checking options like stack overflow and I/O checking. These kinds of options can slow down the zipping and unzipping processes quite a bit.


MakeSFX
MakeSFX Method

Example

Applies to

TVCLZip

Declaration

procedure MakeSFX( SFXStub: String; ModHeaders: Boolean );

Description

Call this method to turn the current zip file (defined by the ZipName Property) into a self extracting zip file. Use your own sfx stub or you may use one of the ones supplied by VCLZip (find them with the Zip Utility Example project file). Specify the path and filename of the SFX Stub that you wish to use in the SFXStub parameter.  If ModHeaders is defined as True, then the zip file header location pointers will be adjusted to compensate for the stub that is added to the beginning of the file.  If ModHeaders is False, then the headers will not be adjusted.

NOTE:  At this time, the value of ModHeaders will be considered to be True no matter what you define it to be.  The headers will always be adjusted.  The capability to NOT adjust headers will be available in a later release.


SFX
Creating a Self Extracting Zip File

If you create a Self Extracting Executable (SFX), The resulting zip file will have the same name as the original zip archive except that it will have an extention of .EXE. This will allow people to unzip files in your zip file without needing to have any kind of unzip utility themselves.  You can do this in two ways, with VCLZip

Use the MakeSFX Method to create a SFX if you have an already existing zip file that you wish to turn into an SFX.

Use the MakeNewSFX method to create a SFX  and zip the files that it will contain, all in one step.  With this method, you also have the capability to add configuration information to the zip file if your stub is capable of this.  VCLZip is distributed with a 32bit sfx stub that does have this capability by using the TSFXConfig Component to create the configuration block.

Here is an example of using the MakeSFX method:

If you have a zip file called data.zip that you want to turn into a self extracting zip file and your SFX stub is called sfx32.exe.  You might use the following code:

begin

With VCLZip1 do

begin

ZipName := 'c:\myfiles\data.zip'      /* the zip archive you want to turn into an SFX */;

MakeSFX( 'c:\sfxstuff\32bit\sfx32.exe', True );  /* note that the second argument is meaningless at this time */

end;

end;

This will result in a file named data.exe in the same directory as data.zip.  The local, central,and end of central headers in data.exe will be modified to reflect their new offsets.

Here is an example of using the MakeNewSFX method using TSFXConfig (defined in the kpSFXCfg unit} along with the 32bit SFX stub that is included with VCLZip.  This example assumes that the stub is called ZipSFX32.bin and is located in the same directory as the running program.:

USES   kpSFXCfg;

VCLZip1.RootDir := 'd:\test\somedir\';  { Start recursive search from here }

VCLZip1.FilesList.Add('*.pas'); { Zip all of the .pas files in the dir structure }

VCLZip1.Recurse := True;  { Recurse subdirectories }

VCLZip1.StorePaths := True;  { Save path information }

sfxcfg := TSFXConfig.Create(nil);  {Create the TSFXConfig object or drop the component on your form }

with sfxcfg do

begin             { Set the options }

UserCanDisableCmdLine := chkUserDisableCmd.Checked;

UserCanChooseFiles := chkUserChooseFiles.Checked;

UserCanChangeOverwrite := chkUserChangeMode.Checked;

OverwriteMode := TsfxOverwriteMode(OverwriteGrp.ItemIndex);

AutoExtract := chkAutoExtract.Checked;

Caption := txtCaption.Text;

DefaultPath := txtDefDest.Text;

CmdLine := txtCmdLine.Text;

InfoText := InfoTextFrm.InfoText.Text;

InfoTitle := InfoTextFrm.InfoTitle.Text;

sfxcfg.CreateHeader;

end;

{ Get the stub }

SFXStub := ExtractFilePath(Application.ExeName) + 'ZipSFX32.bin';

{ Make the SFX file }

if FileExists(SFXFile) then

SysUtils.DeleteFile(SFXFile);

VCLZip1.MakeNewSFX(SFXStub, SFXFile, sfxcfg.theHeader, sfxcfg.HeaderLen);

end;

The following example uses the older stub (ORGSFX32.BIN) and the older kpSFXOpt module. It is better to use the TSFXConfig component described above as it has more options and the newer stub has nicer features.

USES ... , kpSFXOpt;

...

function DoMakeSFX: Integer;

var

SFXStub: String;

NewSFX: String;

SFXCaption, SFXTarget, SFXCmd: String;

begin

    /* Set up zipping options just like you normally would */

VCLZip1.RootDir := 'd:\test\somedir\';  /* Start recursive search from here */

VCLZip1.FilesList.Add('*.pas'); /* Zip all of the .pas files in the dir structure */

VCLZip1.Recurse := True;  /* Recurse subdirectories */

VCLZip1.StorePaths := True;  /* Save path information */

    /* Set up the SFX options with help of kpSFXOpt */

SFXStub := 'C:\sfxstubs\zipsfx32.bin';   /* Where ever your stub is */

NewSFX := 'C:\sfxfiles\mysfx.exe';  /* This will be the new SFX */

setUserCanDisableCmdLine( True );  / * User can disable command line */

setUserCanChooseFiles( False );  /* Don't allow user to select files to extract */

setUserCanChangeOverwrite( True ); /* Allow user to determine overwrite mode */

setOverwriteMode(omAlways ); /* Set default overwrite mode to omAlways */

SFXCaption := 'My SFX';  /* SFX Dialog Caption */

SFXTarget := 'C:\MyApp\'; /* Default target directory for file extraction */

SFXCmd := 'NOTEPAD|><INSTALL.TXT'; /*Run NotePad and show INSTALL.TXT after extraction*/

setStringData( SFXCaption,SFXTarget,SFXCmd );  /* Set the Dialog string options */

SysUtils.DeleteFile( NewSFX );  /* Delete old SFX if it exists */

    /* Create the SFX !!!!   OptionsPointer and OptionsSize are defined in kpSFXOpt */

    Result := VCLZip1.MakeNewSFX( SFXStub, NewSFX, OptionsPointer, OptionsSize );

end;

NOTE: The Demo for VCLZip comes with two SFX stubs, one for creating 16 bit self extracting files and one for creating 32 bit self extracting files.  They are called zipsfx16.bin and  zipsfx32.bin respectively.


FAQ
Frequently Asked Questions

Q: When I try to install the VCLZip component into Delphi 3, I get an error that says VCLZip calls itself recursively.

A: Be sure that the package you are installing the components into does not have the same name as any of the components that you are installing into it.  So don't name the package VCLZip or VCLUnZip.

Q: When I try to set the property OverwriteMode := Always, I get an error that says Always is undefined.

A: If you get this error for any property try adding kpZipObj to your USES list.  Most of the TYPEs are defined there.

Q: When using Delphi 1 I get Integer Overflow and Range Check Errors

A: You need to be sure to turn off Range Checking and Integer Overflow Checking when using Delphi 1.  These errors do not cause a problem.

Q: When adding wildcards to the FilesList without any path information, zipping doesn't seem to work. Why is this?

A: Please remember that you should never count on the DEFAULT DIRECTORY when zipping.  You should always supply a path in some way whether it is as part of the filename itself when added to the FilesList, or by using the RootDir Property.

Q: Why can't I add any comments or files to a spanned or blocked archive?

A: The directory information for the archive must go at the end of the archive which will be on the last disk or possibly even spread over the last 2 or 3 or more disks, depending on how many files are in the archive and this directory information points to the files within that archive.  Adding, replacing, or modifying anything withing a spanned archive would cause enough disk swapping that it would be much easier to just recreate the whole thing.  Once a spanned disk set is created, it cannot be modified in anyway.

Q: When I run my application with VCLZip on my own machine everything works fine.  But when I deploy the application to another system, I get an error that says something like "Class not registered".  Why is this?

A: This error is most likely caused, not by VCLZip, but by some ActiveX component that is part of your application.  VCLZip does not use any OLE, OCX, or ActiveX in any way and should not cause this error.

Q: Why do I get errors when trying to use an application that uses VCLZip, when I have MagicZip active on my system at the same time?

A: This will happen for any application that works with zip files if MagicZip is active.  MagicZip causes zip files to look like normal directories when passed to your application.  There are two things that can help.  One is that you can tell MagicZip the name of your application through it's configuration options.  It maintains a list of applications that it will allow to see zip files normally. Second, I had a registered user tell me that he was able to avoid the problem all together by using names for the zip files in his application with extentions other than .ZIP.

More to come...


Acknowledgments

I would like to acknowledge the following:

•	The INFOZIP Group.  The compression and decompression algorithms in VCLZip and VCLUnZIp are based on the public domain software that makes up the DOS based INFOZIP software written mainly by Mark Adler and Jean-loup Gailly.

•	Ray Lischner, who's buffered io TStream I borrowed (with a few modifications) from his excellent book, Secrets of Delphi 2.

•	William Hall of Compucat Software for the freely distributable 16 and 32 bit SFX stubs.

•	Robert Daignault for his excellent public domain TContain container classes.

•	Christian Ghisler for his public domain Call32NT which made it possible to handle long filenames and other WIN32 API calls with Delphi 1 on WIN95 and NT.

•	Most of all, my wife Jan for all the patience she has shown while I have spent hours upon hours developing VCLZip and VCLUnZip.


ThisVersion
ThisVersion Property

Applies to

TVCLUnZip and TVCLZip

Declaration

property ThisVersion : Integer;

Description

This property simply returns the current version of VCLUnZip and VCLZip.  It is an integer where the last two digits represent the minor version and the remaining digits represent the major version number.  For example, 202 represents version 2.02.  This is a published property and so it can always be seen in the Property Inspector too.


Store83Names
Store83Names Property

Applies to

TVCLZip

Declaration

property Store83Names : Boolean;

Description

When set to True, this will force any long file and pathnames to be stored in DOS 8.3 format.  This is useful if you plan to unzip the files onto a WIN3.X system where long filenames are not valid.  Note however, that VCLUnZip will handle unzipping long filenames to a WIN3.X system properly by shortening the filenames at the time of extraction.


TempPath

Applies to

TVCLZip

Declaration

property TempPath: String;

Description

By default temporary files are created in the system's directory that is defined by the TEMP environment variable. However, in certain situations you may want to direct temporary files to be created somewhere else.  For instance if you are adding files to a large archive, the modified archive is first created as a temporary file.  As long as everything finishes ok then the original archive is replaced by the temporary archive.  If you do not have enough disk space where your default TEMP directory resides, then you may set the TempPath property to a directory where you do have ample disk space available.

IMPORTANT: As of VCLZip 2.21, if the temporary file is on the same disk as the zip file that you are working with, it will be renamed instead of copied, resulting in faster processing for large zip files.  So, while offloading the TempPath to another disk is necessary if disk space is low, having the TempPath on the same drive as zip files that you are ADDING files to will be faster.

You may set this property in either the Object Inspector or within the source code.

Example:

TempPath := 'd:\mytemp';  /* all temporary files will now be created in d:\mytemp */


ResetArchiveBitOnZip

See also

Applies to

TVCLZip

Declaration

property ResetArchiveBitOnZip: Boolean

Description

Setting this to True will cause the Archive Bit for each file to be reset (turned off) after being zipped.

NOTE: Be sure to see SkipIfArchiveBitNotSet as that property will control whether or not files are archived if their archive bit is not set.


SkipIfArchiveBitNotSet

See also

Applies to

TVCLZip

Declaration

property SkipIfArchiveBitNotSet: Boolean

Description

Setting this to True will cause files that do not have their Archive Bit set (turned on) to be skipped during zip operations.  Therefore, while this is set to True, only files with their Archive attribute turned on will be zipped.

NOTE: Be sure to see ResetArchiveBitOnZip as that property (if set to True) will reset the archive bit for each file that is zipped.


PG39
 Filename

Pathname


UnZipToBufferEx
UnZipToBufferEx Method

Applies to

TVCLUnZip

Declaration

function UnZipToBufferEx( var Buffer: PChar; BufferLength: LongInt; FName: String ): Integer;

Description  THIS METHOD NOT IMPLEMENTED YET

The UnZipToBuffer method unzips the file specified by FName parameter from the zip file specified by the ZipName property directly to the memory buffer specified by Buffer pointer parameter.  If the buffer is preallocated, then the length of the buffer must be specified in the BufferLength parameter.

If you pass in Buffer with a value of nil, and/or BufferLength is 0, then Buffer will be allocated at exactly the size of the uncompressed file by VCLUnZip and passed back to you.  It will then be your responsibility to free that memory using a call to FreeMem.

Tip: You can unzip just the first n bytes of any file (possibly to preview the first few bytes in order to determine if you wish to unzip the entire file) to a buffer simply by setting BufferLength to n and by either not defining an OnGetNextBuffer event, or by setting the Cancel parameter of the OnGetNextBuffer event to True the first time it is called.

Return Value

The return value will be 1 if the buffer was extracted and 0 if it was not successfully unzipped.


ZipFromBufferEx
ZipFromBufferEx Method

Applies to

TVCLZip

Declaration

function ZipFromBufferEx( Buffer: PChar; BufferLength, TotalAmount: LongInt; FName: String ): Integer;

Description    THIS METHOD NOT IMPLEMENTED YET

The ZipFromBuffer method allows you to zip information directly from a memory buffer specified by the Buffer parameter. The length of the buffer MUST be specified in the BufferLength parameter.  The filename information that should be stored with the file in the archive must be passed in the FName parameter.  If the TOTAL amount of bytes to be zipped is the same as BufferLength, then the TotalAmount parameter can be left at zero or any number equal to or less than the BufferLength.

If, however, you wish to feed the entire amount to be zipped to VCLZip in chunks of BufferLength size, enter the TOTAL amount of bytes that should be zipped into the TotalAmount parameter.

Return Value

The return value will be 1 if the buffer was zipped and 0 if it was not successfully zipped.


OnGetNextBuffer
OnGetNextBuffer Event

Applies to

TVCLUnZip

Declaration

property OnGetNextBuffer: TGetNextBuffer;

TGetNextBuffer = procedure(Sender: TObject; var Buffer: PChar; FName: String; AmountUsed: LongInt; BufferNum: Integer; var Quit: Boolean) of Object;

Description

Before this event can be called, BufferLength must be set to a value greater than zero.

When unzipping to a memory buffer, if your BufferLength is smaller than the uncompressed size of the file being processed, this event will be called to:

1. Pass you the buffer that was just processed in the Buffer parameter so that you may do whatever you need to do with it.  The AmountUsed parameter will contain the amount of bytes that were written to the buffer.  AmountUsed will typically be the same as BufferLength except for the end of the file which may not fill up the buffer.

2. Allow you to pass back a new buffer pointer, also in the Buffer parameter.  You don't have to change the Buffer pointer if you wish the same buffer to be used again.  If you wish to change the length of the buffer you can by resetting the BufferLength property to a new value.

Also passed to you by this event are:

FName	The name of the file associated with the processing of this buffer at this time.

BufferNum	The sequential number of this buffer being passed in for this file.  The first buffer is number 1.

Quit	If this is passed to you as True then this is the last buffer to be processed for this file.  You may also set this to True at any time to stop processing on the current file.  If you do this then a EUserCanceled exception will be thrown that you may wish to trap.

For an example see  BufferLength.


Wildcards
Working with wildcards

Valid wildcard characters:

*	Matches any number of contiguous characters

?	Matches any single character

<>	Encloses multiple possibilities for a single character

^	Matches anything but what follows inside <>

!	Same as ^

-	Range of characters within <>

*<>	Matches any number of contiguous characters as long is it satisfies the possibilites inside the following brackets.

Examples:

<a-h>	matches any single character from a through h

<!a-h>	matches any single character that isn't a through h

<anplx>	matches any single character as long as it is an a, n, p, l, or x.

*<a-e>	Matches any contiguous characters as long as they are all a thru e

*<!a-e>	Matches any contiguous characters as long as they are all NOT a thru e

'ma?ch.*	Would match match.exe, mavch.dat, march.on, etc

this <e-n>s a <!zy>est	Would match 'this is a test', but would not match 'this as a yest'

c:\windows\sys???\*.ini	Would match c:\windows\system\system.ini, c:\windows\sys001\abc.ini, but not c:\windows\system1\system.ini or c:\windows\sys\defg.ini

Complex wildcards may be used when specifying which files are to be zipped.  This includes wildcard characters not only in the filename but also in the pathname.  This allows you to specify directories using wildcards, for instance:

VCLZip1.FilesList.add('c:\test\w*\mycode*.pas');

would get all PAS files beginning with mycode in subdirectories under TEST that begin with the letter w.  Wilcards may be much more complex than this.


ExcludeList

Applies to

TVCLZip

Declaration

property ExcludeList : TStrings

Description

Add filenames and/or wildcard specifications to this file list to specify files that you do not wish to be included in an archive when zipping.  This is useful, for for example, for excluding things like *.tmp files.

Wildcards may be used when adding to the ExcludeList.

Example:

To exlude all .tmp and .bak files, add the following lines before calling the Zip Method:

... VCLZip1.ExcludeList.Add('*.bak'); VCLZip1.ExcludeList.Add('*.tmp'); ...


NoCompressList

Applies to

TVCLZip

Declaration

property NoCompressList : TStrings

Description

Add filenames and/or wildcard specifications to this file list to specify files that you do not wish VCLZip to attempt to compress when zipping, regardless of what PackLevel is set to. The files that match the entries in this list will be added to the archive with a PackLevel = 0, which means that it will be STORED in the archive with no compression at all.  This is useful when you wish to avoid having VCLZip try to compress files that won't compress much, if any, for instance zip archives that have already been compressed.

Wildcards may be used when adding to the NoCompressList.

Example:

To cause all zip and arj files to be STORED only in an archive when zipping, add the following prior to calling the Zip Method:

... VCLZip1.NoCompressFiles.Add('*.arj'); VCLZip1.NoCompressFiles.Add('*.zip'); ...


Compiler Options
Compiler Options Settings

- It is important to set the following compiler options correctly for your application:

Open parameters	Off

There were several others in the past, however those are now handled in VCLZip's code.


UnZipToBuffer
UnZipToBuffer Method

Applies to

TVCLUnZip

Declaration

function UnZipToBuffer( var Buffer: PChar; FName: String ): Integer;

Description

The UnZipToBuffer method unzips the file specified by FName parameter from the zip file specified by the ZipName property directly to the memory buffer specified by Buffer pointer parameter.  The length of the buffer is expected to be able to handle the length of the file being unzipped which can be determined by the UnCompressedSize Property.

If you pass in Buffer with a value of nil then Buffer will be allocated at exactly the size of the uncompressed file by VCLUnZip and passed back to you.  It will then be your responsibility to free that memory using a call to FreeMem.

Return Value

The return value will be 1 if the buffer was extracted and 0 if it was not successfully unzipped.

Buffered output (using a smaller buffer than the total size of the uncompressed file) is possible by setting the BufferLength property to the size of your buffer, or the amount of output that you want VCLZip to process at a time.  By setting BufferLength, the OnGetNextBuffer Event will be called after each BufferLength bytes have been unzipped.

As an example, the following shows how to unzip directly into a String and attach it to a TMemo component as its text:

n := FileDialog.FileBox.ItemIndex;	/* Get the index of the file to unzip */

SetLength(Buffer, Zipper.UnCompressedSize[n]);	/* Set the length of the string */

BufPtr := @Buffer[1]	/* Point a PChar at the first character of the string */;

Zipper.UnZipToBuffer(BufPtr, CurrentFile );	/* Unzip into the string */

TextMemo.Lines.Text := Buffer;	/* Use that string as the TMemo's text */

See Also:

BufferLength

OnGetNextBuffer

ZipFromBuffer

UnZipToStream

ZipFromStream

UnZipToBufferByIndex


ZipFromBuffer
ZipFromBuffer Method

Applies to

TVCLZip

Declaration

function ZipFromBuffer( Buffer: PChar; Amount: LongInt; FName: String ): Integer;

Description

The ZipFromBuffer method allows you to zip information directly from a memory buffer specified by the Buffer parameter. The length of the buffer MUST be specified in the Amount parameter.  The filename information that should be stored with the file in the archive must be passed in the FName parameter.

Return Value

The return value will be 1 if the buffer was zipped and 0 if it was not successfully zipped.

As an example of using ZipFromBuffer, you might use it to directly zip the contents of a TMemo component such as:

    Zipper.ZipFromBuffer(PChar(TextMemo.Lines.Text), Length(TextMemo.Lines.Text), CurrentFile);

See Also:

UnZipToBuffer

ZipFromStream

UnZipToStream


FileIsOK
FileIsOK Property

Applies to

TVCLUnZip

Declaration

property FileIsOK[Index]: boolean;

Description

This property tests for the integrity of individual files within an archive.

If FileIsOK[Index] is False then that particular file within the archive is probably corrupted.  When this property is first checked, the compressed file is run through a test unzip procedure, exactly as if it was being unzipped except that nothing is actually written out to any file.  If there are any exceptions or errors during the unzip process, the result for this property will be False. Any time you test this property after the first time, while you still have the archive open, it will return the same result, without having to go through the unzipping process (the result is remembered).  However, there is a method called ResetFileIsOK(Index) which you may use to reset this property for a particular compressed file.

If you use this property for a password protected file, be sure to set the password property first, or those password protected files will be reported as being possibly corrupt.

IMPORTANT:  Be sure the DoAll Property is set to False when using this property.  If DoAll is set to True then VCLZip will try to process all of the files in the archive and

NOTE: If you run the FixZip Method on an archive that contains any files that test as being corrupted, those files will not be included in the fixed version of the archive.

If you wish to test the integrity of an entire archive, and the archive has MANY files in it, you should use the CheckArchive procedure. If you have many files in the archive you will find that it will be much faster than using the FileIsOK property.

However, if you wish to test the integrity of an entire archive that does not have MANY files in it, an easy way that would not require an OnBadCRC event would be:

procedure TVCLZipForm.TestZipFilesClick(Sender: TObject);

var

i: Integer;

begin

InfoWin.Lines.Add('Beginning integrity test for ' + IntToStr(Zipper.Count) + ' files for ' + Zipper.ZipName);

For i := 0 to Zipper.Count-1 do

begin

if (Zipper.FileIsOK[i]) then

InfoWin.Lines.Add( Zipper.FullName[i] + ' is OK.' )

else

InfoWin.Lines.Add( Zipper.FullName[i] + ' may be corrupt.' );

end;

Gauge1.Progress := 0;

Gauge2.Progress := 0;

end;

See Also:

CheckArchive

FixZip


PreserveStubs
PreserveStubs Property

Applies to

TVCLZip

Declaration

property PreserveStubs : Boolean;

Description

If PreserveStubs is True, then when opening an SFX archive (self extracting archive) as a zip file and making changes to it (i.e. adding or deleting files), the archive will remain an SFX Archive (in other words, the sfx stub at the beginning of the archive will be preserved).  If PreserveStubs is False, then when making any modifications at all to an SFX archive, the archive will be converted back to a regular zip archive.

The default value for PreserveStubs is False, mainly to preserve backward compatability.

PreserveStubs is a public property.

IMPORTANT: If the sfx archive that you are working with contains any internal checks for the size of the archive then modifying the file may cause the sfx executable to no longer work.

See Also:

MakeSFX Method

Creating a Self Extracting Zip File


SFXToZip
SFXToZip Method

Applies to

TVCLZip

Declaration

procedure SFXToZip( DeleteSFXFile: Boolean );

Description

This will convert an sfx archive to a regular zip archive.  If you want to delete the original sfx file when the conversion is done, then set DeleteSFXFile to True.   The ZipName Property must be set to the SFX file that you wish to convert first.

All header pointers will be properly adjusted during the conversion.

When the conversion is done, the current archive, ZipName, will be set to the newly created ZIP file.

Example:

VCLZip1.ZipName := 'c:\mydirectory\SomeSFX.EXE';  // Set the SFX file to be converted

VCLZip1.ReadZip;  // Cause VCLZip to read the contents of the file

VCLZip1.SFXToZip(True);  // Convert the SFX to a regular ZIP file and delete the old SFX file.


ReplaceReadOnly
ReplaceReadOnly Property

Applies to

TVCLUnZip

Declaration

property ReplaceReadOnly: Boolean

Description

If set to True, allows files with the READONLY attribute to be replaced by an unzip operation.  If set to False, any file that is being unzipped that trys to replace a READONLY file will be skipped and the OnSkippingFile Event will be called.

This is a published property so it can be set in the Object Inspector.

The default value for ReplaceReadOnly is False.


OnUnZipComplete
OnUnZipComplete Event

Applies to

TVCLUnZip

Declaration

property OnUnZipComplete : TUnZipComplete;

TUnZipComplete = procedure(sender: TObject; FileCount : Integer) of Object;

Description

The OnUnZipComplete event handler is triggered at the very end of an UnZip process, after ALL files have been unzipped. Note that this event is not triggered after each file is unzipped.  For that you would use the OnEndUnZip Event.

The FileCount parameter that is passed into the event contains the total number of files that were successfully unzipped.

This event will rarely be used since the same information can be obtained from the return value from the call to the UnZip Method.  This event is mainly can be useful when using VCLZip in threads where in certain circumstances the return from the UnZip method is not seen.

See Also:

OnZipComplete Event, OnEndUnZip Event


OnZipComplete
OnZipComplete Event

Applies to

TVCLZip

Declaration

property OnZipComplete : TZipComplete;

TZipComplete = procedure(sender: TObject; FileCount : Integer) of Object;

Description

The OnZipComplete event handler is triggered at the very end of an Zip process, after ALL files have beenzipped. Note that this event is not triggered after each file is zipped.  For that you would use the OnEndZip Event.

The FileCount parameter that is passed into the event contains the total number of files that were successfully unzipped.

This event will rarely be used since the same information can be obtained from the return value from the call to the Zip Method.  This event is mainly can be useful when using VCLZip in threads where in certain circumstances the return from the Zip method is not seen.

See Also:

OnUnZipComplete Event, OnEndZip Event


MakeNewSFX

Applies to

TVCLZip

Declaration

function MakeNewSFX( SFXStub: String; FName: String; Options: PChar; OptionsLen: Integer): Integer;

Description

This method allows you to create a new Self Extracting Zip File without requiring the in between step of creating a zip file first.  (To make an SFX from an existing zip file, see the MakeSFX Method)  The contents of the zip file will be created using the contents of the FilesList Property,  just as it is used when creating a new regular zip file, and/or a the contents of a zip file specified in the FName paramter (see below).

SFXStub is the filename of the SFX stub file that is to be used to create the SFX.

FName is the filename of the resulting SFX file that is to be created, for instance 'MYSFX.EXE'.  If this filename is, instead, the name of an already existing zip file (.i.e. 'MYSFX.ZIP'), then the files in this zip file will be included in the resulting SFX file. This is in addition to any files that may be specified in the FilesList.  The name of the resulting SFX file in this case will be the same as the zip file except with an extention of .EXE.

Options and OptionsLen:

This method is designed to work well with the 32bit SFX stub that is supplied with VCLZip (ZIPSFX32.BIN) configurable by adding a configuation block between the stub and zip file.   The Options and OptionsLen parameters are specifically for this purpose.  Options should point at the options memory block (remember to cast as a PChar) and OptionsLen should be set to the length of that block in bytes.  If you do not have an options block, or your stub is not compatible with the options block, just set the Options parameter to nil and set OptionsLen to zero.

The return value is the number of files that were successfully zipped into the SFX file.

Additionally, if you use the TSFXConfig Component, along with the 32bit SFX stub that is distributed with VCLZip, this allows you to easily create a configurable 32bit SFX.  The Options and OptionsLen values are set for you and other options are easy to set:  See TSFXConfig for an example.


kpSFXOpt

unit kpSFXOpt;

You should use the TSFXConfig component instead of this module with the newer sfx stub as of VCLZip 2.20.

This unit allows for the easy creation of a 32bit configurable SFX if using the SFX stub that is supplied with VCLZip, especially when using the MakeNewSFX method.  The following procedures set the different options allowed in the 32bit SFX that is distributed with VCLZip.

var

OptionsPointer: PChar; /* Pointer to the options block, used in the MakeNewSFX method. */

OptionsSize: Integer /* Length of the options block, used in the MakeNewSFX method. */

procedure setUserCanDisableCmdLine( Value: Boolean );

Set Value to True if you want the SFX dialog to have a checkbox which allows the user of the SFX to disable the running of the command line (see setStringData below to see how to set up the command line).  The default Value is False.

procedure setUserCanChooseFiles( Value: Boolean );

Set Value to True if you want the end user of the SFX to be able to select the files in the listbox to be extracted.  If set to False (the default), all files will be extracted.

procedure setUserCanChangeOverwrite( Value: Boolean );

Set Value to True if you want the end user to be able to determine the overwrite mode through a set of option buttons on the dialog box.  If set to False, the overwrite mode will be set to the default overwrite mode which you can set using the setOverwriteMode (below), and the end user won't be able to change it.

procedure setOverwriteMode( om: TsfxOverwriteMode );

Set om to the value you want the default overwrite mode to be.  The default value is omPrompt.  The allowable values are:

  omPrompt	A dialog box will be diplayed asking the user if they wish to overwrite an existing file with the file currently being unzipped.

  omAlways	Always overwrite any existing files.

  omNever	Never overwrite any existing files, do not extract if file already exists.

procedure setAutoRun( Value: Boolean );

Setting this value to True will cause the SFX to automatically run and extract its contents to the destination path that you set in the call to setStringData (see below).  In this case, upon double clicking, the sfx will automatically run without any intervention from the user.  A window will not appear.  You can still have the sfx execute a program or file when done by setting the sfxCmdLine in your call to setStringData.

procedure setStringData( sfxCaption, sfxDefPath, sfxCmdLine: String );

Set the string options for the SFX dialog:

  sfxCaption	The SFX Dialog's caption

  sfxDefPath	The default extraction directory shown in the dialog's target directory text box.  The user will be able to change this. If set to '><', the files will be extracted to the system temporary directory.  The default is '' which means the directory will first be set at the same directory as where the SFX itself resides. (e.g. "><readme\test.txt" after an extraction to the path "C:\Program files\unpacked" means : "c:\progra~1\unpacked\readme\test.txt") <- the short path will be created by zipsfx.

  sfxCmdLine	The command line to execute after all files have been extracted. If the string "><" (greater than+less than) is somewhere in the command line, it will be replaced with the path where the archive has been extracted to.

If the pipe "|" is in the command-line, the part to the left will get the application to run and the part to the right will be it's argument.  if the archive is extracted to e.g. "d:\unpack", then we will get the following :

 "><setup\setup.exe|><install.inf" will parse to :

run "d:\unpack\setup\setup.exe" with parameters  "d:\unpack\install.inf".

 "c:\windows\notepad.exe|><readme.txt" will parse to :

run "c:\windows\notepad.exe" with parameters  "d:\unpack\readme.txt".

"><readme.txt" will parse to :

open "d:\unpack\readme.txt" with its associated program, if there is any.

"><setup.exe" will run "d:\unpack\setup.exe" without special parameters.


Selected

Applies to

TVCLUnZip

Declaration

property Selected[ Index ]: Boolean;

Description

Setting this property to True for any file in an archive will allow you to unzip it using one of the unzip methods that unzip files based on its index.  For instance the following will unzip all files .TXT files in the archive:

With VCLZip1 do begin ZipName := 'c:\test\test.zip';  /* Open existing zip file */

For i := 0 to Count-1 do

If UpperCase(ExtractFileExt(Filename[i])) = '.TXT' then

Selected[i] := True;  /* Flag text files as selected */

DestDir := 'c:\test\newdir';

NumUnZipped := UnZipSelected;

end;

After returning from the UnZipSelected method, all files will have their Selected property set back to False;

See Also:

ClearSelected

NumSelected

UnZipSelected


DecryptHeader

Applies to

TVCLUnZip

Declaration

property DecryptHeader[ Index ]: DecryptHeaderType

DecryptHeaderType = array[0..11] of BYTE;

Description

The DecryptHeader property will return the 12 byte decryption header for an encrypted file in an archive.  This is only useful for applications that wish to test the password for encrypted files in a more low level way.  Normally VCLZip will handle all of this for you internally.

If you are developing in BCB you should use the GetDecryptHeaderPtr method instead.

See Also:

Crc

Password

DecryptHeaderByte

GetDecryptHeaderByteByPtr

GetDecryptHeaderPtr


UnZipToStreamByIndex

Applies to

TVCLUnZip

Declaration

function UnZipToStreamByIndex( theStream: TStream;  Index: Integer ): Integer;

Description

The UnZipToStreamByIndex method is the same as the UnZipToStream Method except that you pass in the Index instead of the filename of the file to be unzipped.  It unzips the file specified by the Index parameter from the zip file specified by the ZipName Property directly to the stream specified by theStream parameter.

For example the following will unzip the first .TXT file in the archive:

myStream := TMemoryStream.Create;

While i < Count do

If UpperCase(ExtractFileExt(Filename[i])) = '.TXT' then

begin

UnZiptoStreamByIndex( myStream, i );

break;

end;

See Also:

UnZip

UnZipSelected

UnZipToBufferByIndex

UnZipToBuffer

UnZipToStream


UnZipSelected

Applies to

TVCLUnZip

Declaration

function UnZipSelected: Integer;

Description

The UnZipSelected method causes the files that have had their Selected property set to True, to be extracted. The return value is the number of files successfully unzipped.

The following will unzip all .TXT files:

  With VCLZip1 do

For i := 0 to Count-1 do

If UpperCase(ExtractFileExt(FileName[i])) = '.TXT' then

Selected[i] := True;

NumUnZipped := UnZipSelected;

See Also:

UnZip

UnZipToStreamByIndex

UnZipToBufferByIndex

Selected


UnZipToBufferByIndex

Applies to

TVCLUnZip

Declaration

function UnZipToBufferByIndex( var Buffer: PChar; Index: Integer ): Integer;

Description

The UnZipToBufferByIndex method unzips the file specified by the Index parameter from the zip file specified by the ZipName property directly to the memory buffer specified by Buffer pointer parameter.  The length of the buffer is expected to be able to handle the length of the file being unzipped which can be determined by the UnCompressedSize Property.

If you pass in Buffer with a value of nil then Buffer will be allocated at exactly the size of the uncompressed file by VCLUnZip and passed back to you.  It will then be your responsibility to free that memory using a call to FreeMem.

Return Value

The return value will be 1 if the buffer was extracted and 0 if it was not successfully unzipped.

As an example, the following shows how to unzip directly into a String and attach it to a TMemo component as its text:

n := FileDialog.FileBox.ItemIndex;	/* Get the index of the file to unzip */

SetLength(Buffer, Zipper.UnCompressedSize[n]);	/* Set the length of the string */

BufPtr := @Buffer[1]	/* Point a PChar at the first character of the string */;

Zipper.UnZipToBufferByIndex(BufPtr, n );	/* Unzip  into the string */

TextMemo.Lines.Text := Buffer;	/* Use that string as the TMemo's text */

See Also:

ZipFromBuffer

UnZipToStream

UnZipToStreamByIndex

ZipFromStream


AddDirEntriesOnRecurse

Applies to

TVCLZip

Declaration

property AddDirEntriesOnRecurse: Boolean

Description

If AddDirEntriesOnRecurse is True, then when you do a recursive search through subdirectories (Recurse = True) a separate entry will be made in the archive for each directory.  This will allow even empty directories to be restored.

If AddDirEntriesOnRecurse is False, path information will still be stored with each file that is compressed, but a separate entry will not be inserted for the directories.

This property has no meaning unless Recurse = True.

The resulting directory entries will have a Filename[Index] = '' (a blank filename) but will have a value for Pathname[Index].  When unzipping, these entries will cause that particular directory to be created if RecreateDirs = True.

Default value is False.

See Also:

Recurse

RecreateDirs


ClearSelected

Applies to

TVCLUnZip

Declaration

procedure ClearSelected;

Description

Call this procedure to set the Selected property for all files to False;

See Also:

Selected

NumSelected

UnZipSelected


CheckArchive

Applies to

TVCLUnZip

Declaration

functionCheckArchive: Boolean;

Description

This method is used to check the integrity of an entire archive.  It will process the archive specified by ZipName. In order to test the integrity of a single file within an archive, use the FileIsOK Property.

This function will return True if the archive tests ok and false if any of the files do not test ok.  This could be one or more files that are corrupt in the archive.  In order to tell which files are corrupt during the call to CheckArchive, you should define a OnBadCRC Event which will be called for each bad file.  Using the FileIndex parameter that is passed in to this event procedure, you can tell which file is bad.

IMPORTANT:  Please be aware that CheckArchive will clear the FilesList, so you will have to populate the FilesList AFTER calling CheckArchive if you plan on using FilesList to zip or unzip specific files after calling CheckArchive.

See Also:

FileIsOK Property

FixZip Method


OnUpdate
OnUpdate Event

Applies to

TVCLZip

Declaration

property OnUpdate : TUpdateEvent

TUpdateAction = (uaReplacing, uaKeeping);

TUpdateEvent = procedure( Sender: TObject; UDAction: TUpdateAction;  FileIndex: Integer ) of Object;

Description

The OnUpdate event is fired only when updating or freshening an existing archive.  It will be called for each file that is already in the archive and the UpdateAction will be passed in.  Each file will either be kept as is (uaKeeping) or replaced by a newer file (uaReplacing).

Note that at this time, this is the only progress type of notification there is for files that are kept as they are copied from the original zip file to the new zip file.


SaveZipInfoOnFirstDisk

Applies to

TVCLZip

Declaration

property MultiZipInfo.SaveZipInfoOnFirstDisk: Boolean;

Description

This property determines whether VCLZip will save a special Zip Configuration File on the first disk of a spanned zip file, when creating a spanned zip file (this works for blocked zip files too - that is spanned zip files created directly to your hard drive).  This will allow VCLZip to open the spanned zip file from the first disk of the set instead of requiring the last disk to be inserted.

Normally, PKZip compatible spanned zip files require that the LAST disk of the disk set be inserted first in order to open up the zip file.  This often creates confusion and is an annoyance.  VCLZip has the unique capability to create and read spanned zip files which will allow VCLZip to open a spanned zip file from the first disk.  This option does not cause the spanned zip file to be non-PKZip compatible as PKZip, WinZip, and all of the other zip utilities can still open and read the spanned zip file normally (from the last disk).  However, VCLZip will, if this option is set to True, write some extra information onto the first disk in a separate file.  VCLZip will detect this file if the first disk is inserted first, and read from it, the information it would otherwise need the last disk to obtain.

If this property is set to True before calling the Zip Method to create spanned zip file, then when the zip file has been completely created, VCLZip will ask you to re-insert the first disk of the spanned zip file.  VCLZip will then write out a special file called a Zip Configuration File which will be named the same as your zip file except it will have an extention of '.ZFC'.  If this first disk is ever the first disk inserted when trying to open up the zip file (which is a common mistake among users), VCLZip will automatically detect this file and use the information from it to get the contents of the spanned zip file.

Note that other zip utilities will not be able to make use of this feature, only VCLZip will be able to use this file.

IMPORTANT: VCLZip will attempt to save enough room on the first disk to allow for the Zip Configuration File to be written.   This amount will be added to the SaveOnFirstDisk property in the case of writing directly to removable media (MultiZipMode = mmSpan) or subtracted from the FirstBlockSize property in the case of creating the spanned zip file directly to the hard drive (MultiZipMode = mmBlocks).  If you are storing file comments,  fairly long filenames, or longer than usual path information, you may find that you might need to adjust the SaveOnFirstDisk or the FirstBlockSize property ahead of time to compensate for this somewhat.

Basically the size of the Zip Configuration File, in bytes, will be approximately:

( Total Number of files * 46) + length of all filenames (including path information if saved) + length of each file comment + 22 + length of the zip comment.


SaveOnFirstDisk

See also	Example

Applies to

TVCLZip

Declaration

property MultiZipInfo.SaveOnFirstDisk : LongInt

Description

Use this property when creating Spanned Disk Zip Files to save some room on the first disk for other files such as installation/setup files and/or a Zip Configuration File (which allows VCLZip to open a spanned zip file from the first disk instead of the normally required last disk).

See Also:

SaveZipInfoOnFirstDisk

Creating Spanned Disk Zip Files

MultZipInfo Properties


DecryptHeaderByte
DecryptHeaderByte Method

Applies to

TVCLUnZip

Declaration

function DecryptHeaderByte( Passwrd: String; dh: DecryptHeaderType ): BYTE;

Description

This function is used in conjunction with the DecryptHeader property to determine if a password matches the password key of a file.  This function is only needed if doing low level work with passwords and encrypted zip files.

If you are developing in BCB you should use the GetDecryptHeaderPtr method instead.

See Also:

DecryptHeader

GetDecryptHeaderByteByPtr

GetDecryptHeaderPtr


GetDecryptHeaderByteByPtr

Applies to

TVCLUnZip

Declaration

function GetDecryptHeaderByteByPtr( Passwrd: String; dh: BytePtr ): Byte;

Description

This method is mainly for use in BCB and is analogous to the DecryptHeaderByte Method which should be used if developing in Delphi.

You should pass dh in as a 12 byte array that should previously be filled in by a call to GetDecryptHeaderPtr.

This function is used in conjunction with the GetDecryptHeaderPtr to determine if a password matches the password key of a file.  This function is only needed if doing low level work with passwords and encrypted zip files.

See Also:

DecryptHeader

DecryptHeaderByte

GetDecryptHeaderPtr


GetDecryptHeaderPtr

Applies to

TVCLUnZip

Declaration

procedure GetDecryptHeaderPtr( Index: Integer; dhPtr: BytePtr);

Description

This method is mainly for use in BCB and is analogous to the DecryptHeader which should be used if developing in Delphi.

You should allocate dhPtr prior to calling this method, as a 12 byte array.

This method should only be called for files that are password encrypted, however if you do call this method for a file that is not password encrypted, the 12 byte array that dhPtr points to, will contain all zero's.

This function is used in conjunction with the GetDecryptHeaderByteByPtr method to determine if a password matches the password key of a file.  This function is only needed if doing low level work with passwords and encrypted zip files.

See Also:

DecryptHeader

DecryptHeaderByte

GetDecryptHeaderByteByPtr


What's New
What's New in this version

History for VCLZip 2.20 and earlier

Version 2.22

•	Now Delphi 6 compatible.

•	New event called OnRecursingFile which gets called as VCLZip recurses directories searching for files that match a wildcard that is entered in the FilesList.  This gets called each time a file matches the wildcard.

•	Fixed a bug which kept diskettes from being labeled when creating spanned zip files on WIN31.

•	Fixed a bug which sometimes did not allow zip comments to be added to blocked zip sets.

•	Fixed a bug which caused VCLZip to not properly handle the IncompleteZip exception on spanned zip sets unless you called ReadZip prior to calling UnZip.

Version 2.21

•	When working with temporary files, VCLZip will now rename, instead of copy, the temp file if the destination is on the same drive. This will speed up the adding of files to an existing zip file when the resulting zip file is very large.

•	New event called OnPrepareNextDisk which is an event that will allow you, when creating spanned zip files across diskettes, to do things like format a diskette that has just been inserted, or to add or delete files from the diskette before continuing with the zipping process.

•	Fixed a problem that was causing the CancelTheOperation Method to not work properly.

•	Fixed bug which caused VCLZip to miscalculate space needed for zfc file if wildcards are put into the FilesList.

•	Fixed bug so you could use an OnFilePercentDone event without needing an  OnTotalPercentDone event when creating spanned zip files

•	Fixed so header relative offset set correctly for spanned zips. This was a side effect of removing needless write of header.

•	Added code to read local fileheaders if exception thrown when reading a central fileheader.

•	Fixed problem where directories couldn't be created from directory entries because the fullpath wasn't known yet.  Result of having moved this code to earlier.

•	Fixed typo in creation of LOC header values which could cause error if reading local headers.

•	Changed so Zip Comment starting position is calculated based on end of central record instead of end of file.

•	IMPORTANT: Changed default for FileOpenMode back to fmShareDenyNone as it had been for all but version 2.20.  This allows VCLZip to backup open files.  If you do not want this behavior please set FileOpenMode accordingly.

•	Fixed a problem where drivepart (i.e. C:\) was not being stripped when saving relative paths.

•	Added a BufferedStreamSize property which can increase the speed of creating zips to floppy (and other slow media) dramatically.  The new default for this should increase the speed by as much as 3 times, but you can now tweak this especially for your application!

•	Fixed a problem where zip comments in zfc files were not being read correctly.

•	Added a setZipSignatures procedure which allows you to modify the signatures of your zip file. This will cause other zip utilities to not be able to recognize or read your zip files created with VCLZip. Useful if you want to add further security to your zip files.

•	Some zip files would not open correctly, throwing an incomplete zip file exception due to an erroneous "extra field length" identifier in headers of some compressed files. These zip files are rare, but a very few people seemed to have several of them. This problem would not affect zip files created by VCLZip, and this problem should only occur in VCLZip 2.20, not in any previous version.

•	If you had Range Checking turned on, VCLZip would get a range check error when using a wildcard that ended with a * as in 'somefile.*'.

•	Under certain circumstances, drive information would not be stripped from path information if zipping recursively (including subdirectories)

•	"Retrying" to zip a file that could not be opened using the OnSkippingFile Event would not always work correctly.

•	Creating spanned zip set to floppy should be faster now due to removing a needless header write to disk for each file.

•	VCLZip would not compile correctly with MAKESMALL defined.

•	Added code to make VCLZip work with BCB5.

•	Added readonly boolean ImproperZip property which will be set to True when some sort of problem is found when opening the zip file, even if recoverable. This property will be enhanced and refined in the future.

•	If KeepZipOpen is set to True, when putting in the wrong disk in a spanned zip set, VCLZip would not always properly close the file on the old diskette before trying to open the file on the next diskette.

•	Added ECantWriteUCF exception which will be thrown if VCLZip runs out of room to write the uncompressed file when unzipping.

•	Timestamp was not being set properly when unzipping readonly files. Moved setting of the timestamp to before the attributes get set.


BufferLength

Applies to

TVCLUnZip

Declaration

property BufferLength : LongInt;

Description

Setting BufferLength to some value greater than zero, allows buffered output when unzipping directly to memory. Setting this property before calling either of the UnZipToBuffer methods...

UnZipToBuffer

UnZipToBufferByIndex

to some value less than the total uncompressed size of the file being extracted will cause the OnGetNextBuffer Event event to be called every time BufferLength bytes have been unzipped.

This can be useful also if you wish to preview what is in a large file without unzipping the entire file.  Or if you wish to be able to see a large file in an editor before the entire file is opened up into it.

As an example, the following will unzip a file into a string buffer.  BufferLength is set to 1/4th of the length of the string buffer in order to show how OnGetNextBuffer gets called:

var

sBuffer, CurrentFile: String;

tempPointer: pChar;

n: Integer;

begin

    n := FileDialog.FileBox.ItemIndex;	 /* Get index number of file to be unzipped */

CurrentFile := LowerCase(FileDialog.SelectedFile.Text);	/* Get the filename to be unzipped */

SetLength(sBuffer, Zipper.UnCompressedSize[n]);	/* Set string length to uncompressed size of the file */

tempPointer := @sBuffer[1];	/* PChar pointer to begining of string */

Zipper.BufferLength := Length(sBuffer) div 4;	/* Set the BufferLength */

Zipper.UnZipToBuffer(tempPointer, CurrentFile );	/* Unzip the file into the string */

TextMemo.Lines.Text := sBuffer;	/* Point a textmemo at it so you can see it */

end;

/* The OnGetNextBuffer event */

procedure TForm1.ZipperGetNextBuffer(Sender: TObject; var Buffer: PChar; FName: String; AmountUsed, BufferNum: Integer; var Quit: Boolean);

begin

Buffer := Buffer + AmountUsed;  /* Slide the buffer pointer to the end of what has already been unzipped /*

end;

Notice how the buffer pointer is slid along the string so that the next output from VCLZip will be appended to the end of what has already been unzipped.  You can also leave the pointer at the same position if you wish to use the same buffer over and over again.  You might use this technique if you simply copy the output from the buffer each time the OnGetNextBuffer event is called.


NumSelected

Applies to

TVCLUnZip

Declaration

property NumSelected[ Index ]: Integer;

Description

NumSelected reflects the number of compressed files that have been selected with the Selected property.

After an unzip operation this number will be zero as all selections will be cleared.

See Also:

Selected

ClearSelected

UnZipSelected


Properties
Properties List

Property	Description

Filename[i]	Filename portion of i'th file in archive

Pathname[i]	Pathname portion of i'th file in archive

FullName[i]	Full pathname+filename of i'th file in archive

CompressMethod[i]	Compression method used for i'th file in archive

CompressMethodStr[i]	Compression method in string format for i'th file in archive

DateTime[i]	Datestamp of the i'th file in archive

Crc[i]	CRC value of i'th file in archive

CompressedSize[i]	Compressed size of the i'th file in archive

UnCompressedSize[i]	Uncompressed size of the i'th file in archive

IsEncrypted[i]	Returns True if i'th file in archive is password encrypted

FileHasComment[i]	Returns True if i'th file in archive has a comment

FileComment[i]	The comment for the i'th file in the archive

ExternalFileAttributes[i]	The external file attributes for the i'th file in the archive

DiskNo[i]	Disk number in a spanned archive that the i'th file in the archive starts on.  Always 1 for non-spanned archive

Selected[i]	Set to True if you want to flag to be unzipped by the UnzipSelected method.

DecryptHeader[i]	Returns the decryption header for the i'th file in the archive

FileIsOK Property[i]	Returns True if the i'th file in the archive is not corrupted.

Count	Returns the number of compressed file entries in the archive

ZipHasComment	Returns True if the archive has a ZipComment

ZipComment	Returnst the zip comment of the archive

Password	Set this before zipping to the desired password before zipping to create an encrypted archive.  Set before unzipping to unzip encrypted files

NumDisks	Returns number of disks in spanned archive.  Always 1 for non-spanned archives

ZipSize	Returns, in bytes, the size of the archive.  Only returns the size of the currently open file for a spanned archive

CheckDiskLabels	Set to True if you want VCLZip to check for pkzip compatible disk labels to be sure user puts in the correct disk when unzipping spanned archives

MultiMode	Set to determine what kind of zip file you want to create... normal, spanned or blocked

ArchiveStream	Set this to a memory stream, blob stream, etc. to create or work with archives in memory

Busy	Returns True if VCLZip is busy with a zip or unzip operation

NumSelected	Returns the number of compressed files for which you have set the Selected property to True.

BufferLength	Used with the UnZipToBuffer methods to implement buffered unzips to memory where your buffer is smaller than the uncompressed file.  Unzips in chunks

ZipName	Set to the name of the archive you wish to work with.  Include volume and pathname.

DestDir	The directory to which you wish to unzip files

RootDir	Used for several different things including saving of relative path information

SortMode	Determines the order that the indexed properties will access the archives files.  Does not affect the actual order of the files in the archive

RecreateDirs	Set to True if you want use the stored path information when unzipping files

OverwriteMode	Determines how VCLZip will behave when unzipping files over files that already exist on your hard drive

FilesList	Fill this with the files that you wish to zip or unzip.  Wildcards are allowed.

DoAll	Set to True if you want to unzip ALL files in an archive

IncompleteZipMode	Determines VCLZip's behavior when encountering a file that isn't a completely valid zip file

KeepZipOpen	Set to True if you want VCLZip to keep the zip file open between zip and unzip operations

DoProcessMessages	Set to True if you want VCLZip to call Application.ProcessMessages durning zip and unzip processes

RetainAttributes	set to true if you wish unzipped files to retain the attributes that they had when they were originally zipped.

ThisVersion	Reflects the current version of VCLZip

ReplaceReadOnly	Set to True if you wish VCLZip to attempt to overwrite ReadOnly files when unzipping

PackLevel	Determines the level of compression when zipping files.  Valid is 0-9 where 0 is no compression (fastest) and 9 is highest compression (slowest)

Recurse	Set to True if you want VCLZip to recurse through subdirectories when zipping.  Only meaningful if using a wildcard.

Dispose	Set to True if you want VCLZip to delete files from your hard drive that it has zipped, after zipping them

StorePaths	Set to True if you want to store path information with each file when zipping

StoreVolumes	Set to True if you want to store volume information with each file when zipping.  This makes the archive NON-pkzip compatible

ZipAction	Set to determine how VCLZip replaces files already in an archive when zipping.  You can replace, update, or freshen

RelativePaths	Set to True if you wish to store relative paths when storing path information when zipping recursively through sub directoires

Store83Names	Set to True if you wish to store only short filename (8.3 format)

TempPath	Set to the path where you wish VCLZip to write it's temporary files when zipping.

ResetArchiveBitOnZip	Set to True if you want VCLZip to reset each file's archive bit once it has zipped a file

SkipIfArchiveBitNotSet	Set to True if you want VCLZip to only include files who's archive bit is set when zipping

ExcludeList	Add filenames and wildcards to this list for files and types of files that you do not want zipped.

NoCompressList	Add filenames and wildcards to this list for files and types of files that you want included but not compressed (packlevel=0) when zipping.

AddDirEntriesOnRecurse	Set to True if you want separate entries in the archive for directories when doing recursive zips through subdirectories.  This is especially useful when you want to be able to restore empty directories

PreserveStubs	Set to True if you want VCLZip to retain the SFX stub on archives when doing zip and unzip processes

IsModified	Returns True if certain properties of an archive have been modified, such as a comment or filename or pathname. SaveModifiedZipFile should be called to save modified information

FlushFilesOnClose	will cause all files opened for write by VCLZip to have their disk buffers flushed to disk when closed.

FileOpenMode	Determines the file open mode for files being opened to be zipped into an archive.

BufferedStreamSize	Sets the buffer size for the buffered file i/o.

ImproperZip	Readonly property that is set to True when VCLZip detects some inconsistency in the zip structure.

MultZipInfo Properties	Properties dealing with MultiVolume archives

MultiMode	Determines the type of archive (normal, spanned, or blocked)

BlockSize	Determines the size of each block for blocked zip files

FirstBlockSize	Determines the size of only the first block of a blocked zip file

SaveOnFirstDisk	Determines the amount of space to save on the first disk of a spanned archive

SaveZipInfoOnFirstDisk	Set to True if you wish VCLZip to save a Zip Configuration File when creating a spanned or blocked archive, allowing you to open the archive from the first disk

CheckDiskLabels	Set to True if you want VCLZip to check for pkzip compatible disk labels to be sure user puts in the correct disk when unzipping spanned archives

WriteDiskLabels	Set to True if you want VCLZip to write pkzip compatible disk lables when creating spanned archives.


Methods
Methods List

Method	Description

ReadZip	Reads in the zip information

UnZip	Extracts files from the archive based on what is in the FilesList

UnZipSelected	Extracts files from the archive based on which files have their Selected property set to True

UnZipToStream	Extracts a particular file (based on a filename) to your own stream

UnZipToStreamByIndex	Extracts a particular file based on it's index into your own stream

UnZipToBuffer	Extracts a file directly to a memory buffer

UnZipToBufferByIndex	Extracts a file, based on it's index, directly into a memory buffer

ClearZip	Clears the current archive information out of memory

FillList	Puts information about an archive into a string list

Sort	Determines the order in which the indexed properties access the information about each file in an archive

CancelTheOperation	Causes a zip or unzip operation to stop

ResetFileIsOK	Will clear the current value of FileIsOK so that the file will be physically tested again the next time the FileIsOK property is checked

ClearSelected	Clears the selected properties of any files that may have their selected property set to True

CheckArchive	The best way to check the integrity of all files in an archive

GetDecryptHeaderPtr	Same as the DecryptHeader property except this method works better for BCB

GetDecryptHeaderByteByPtr	Same as the DecryptHeaderByte property except this method works better for BCB

Zip	Compresses the files in FilesList into the archive

DeleteEntries	Deletes entries from an archive based on what is in FilesList

SaveModifiedZipFile	Saves a zip file that has had certain types of changes made to it

ZipFromStream	Compresses information from your stream into the archive

ZipFromBuffer Method	Compresses information from your memory buffer into the archive

setZipSignatures	Optionally change the header signatures used to create and open zip files

FixZip	Does it's best to fix an archive that may have corrupted files in it

MakeSFX	Connects an SFX stub to a zip archive to create a Self Extracting Archive

MakeNewSFX	More powerful way to create a Self Extracting Archive

SFXToZip	Will convert a self extracting archive into a normal zip file


Events
Events List

Method	Description

OnStartUnzipInfo	Provides information totals before unzipping any files

OnStartUnZip	Provides information about each file just before it is unzipped.  Allows you to change the destination and filename

OnFilePercentDone	Provides progress on the current file being zipped or unzipped

OnTotalPercentDone	Provides progress on all files being zipped or unzipped as a whole

OnEndUnZip	Triggered just after each file is unzipped

OnPromptForOverwrite	Allows you to do processing or interact with the user to determine what to do about a file that is about to be overwritten by a file that is being extracted from an archive

OnSkippingFile	Provides a reason for a file that is being skipped over while zipping or unzipping

OnBadPassword	Triggered when unzipping a with an incorrect password

OnBadCRC	Triggered when a file is probably corrupted because the CRC and the internally stored CRC are not the same

OnInCompleteZip	Triggered when an attempt is made to open a zip file that can't be opened

OnGetNextDisk	Triggered when a new disk is needed when zipping or unzipping a multivolume zip file

OnPrepareNextDisk	Triggered just after OnGetNextDisk and just before zipping to allow you to prepare the disk (i.e. format, delete files, etc)

OnUnZipComplete	Signals that all unzipping is finished

OnGetNextBuffer	Allows processing and changing of buffers during buffered unzips to memory

OnStartZipInfo	Provides information totals before zipping any files

OnStartZip	Provides information about each file just before it is zipped.  Allows you to change some internal information about the file

OnEndZip	Triggered just after each file is zipped

OnDeleteEntry	Ttriggered just before a zip entry is about to be deleted from the zip file

OnDisposeFile	Triggered just before a file is deleted when using the Dispose property

OnNoSuchFile	Triggered when you have entered a file into the FilesList Property zipped and there is no such file.

OnZipComplete	Signals that all zipping is finished

OnUpdate	Triggered for each file that already exists in an archive to let you know that it is either being replaced or kept

OnRecursingFile	Called as each file is found that matches the wildcard when recursing directories.  This happens before any zipping takes place


FlushFilesOnClose

Applies to

TVCLUnZip

Declaration

property FlushFilesOnClose: Boolean

Description

When set to True this property will cause all files that are open for write to have their disk buffers flushed when they are closed.  When the file is closed, the API call to FlushFileBuffers is made.

This only has an effect ofcourse, on files opened for write and no effect on files opened for reading only.  So when unzipping, this would cause the disk buffers to be flushed for the files that have been extracted, and when zipping, this would cause the archive being created to have it's buffers flushed to disk when closed.

This property has no effect at all, when in a Delphi 1 (16bit) environment or when you have NOSTREAMBUFF defined.


FileOpenMode

Applies to

TVCLZip

Declaration

property FileOpenMode: Word;

Description

IMPORTANT: As of version 2.21, default for FileOpenMode was changed back to fmShareDenyNone as it had been for all but version 2.20.  This allows VCLZip to backup open files.  If you do not want this behavior please set FileOpenMode accordingly.  In version 2.20 the default was fmShareDenyWrite.

This property allows you to define the open mode for opening files that are about to be zipped.  If a file cannot be opened with this mode, then the OnSkippingFile Event will be called to let you know that file will not be zipped because it is already open by another process, and allow you to close that file and continue. This ONLY affects the opening of files that are being zipped.

The default value is (fmOpenRead or fmShareDenyNone).  This setting will allow VCLZip to backup files that are opened by other applications.

You would set this property for instance if you want to be sure that VCLZip only backs up files if they are not opened by any other process at all.  In this case you would set this property as

FileOpenMode :=  fmOpenRead or fmShareExclusive;

From the Delphi Help File:

The Mode parameter indicates how the file is to be opened. The Mode parameter consists of an open mode and a share mode or’ed together. The open mode must be one of the following values:

Value	Meaning

fmCreate	Create a file with the given name. If a file with the given name exists, open the file in write mode.

fmOpenRead	Open the file for reading only.

fmOpenWrite	Open the file for writing only. Writing to the file completely replaces the current contents.

fmOpenReadWrite	Open the file to modify the current contents rather than replace them.

The share mode must be one of the following values:

Value	Meaning

fmShareCompat	Sharing is compatible with the way FCBs are opened.

fmShareExclusive	Other applications can not open the file for any reason.

fmShareDenyWrite	Other applications can open the file for reading but not for writing.

fmShareDenyRead	Other applications can open the file for writing but not for reading.

fmShareDenyNone	No attempt is made to prevent other applications from reading from or writing to the file.


kpSFXCfg
TSFXConfig Component

Example

TSFXConfig = class(TComponent)

kpSFXCfg.pas

You should use this component instead of kpSFXOpt with the newer sfx stub as of VCLZip 2.20.

This unit allows for the easy  modification of options for the 32bit configurable SFX Delphi stub that is supplied with VCLZip.  Use this in conjunction with the MakeNewSFX method.

The following properties and methods of TSFXConfig set the different options allowed in the 32bit SFX that is distributed with VCLZip.

PUBLIC

procedure CreateHeader;

Call this method after you have set all options and you are ready to call MakeNewSFX  This will actually create theHeader, which is the options header that is passed into MakeNewSFX.

property theHeader: PChar read FHeader;

This is the options header that you pass into MakeNewSFX.  It will be placed between the sfx stub and the zip file when the SFX is created.  theHeader is created by calling CreateHeader after all options have been set.

property HeaderLen: WORD read FHeaderLen;

This is the length of the resulting options header that is created when you call CreateHeader.  This length is passed into MakeNewSFX along with theHeader.

PUBLISHED

property tUserCanDisableCmdLine( Value: Boolean );

Setto True if you want the SFX dialog to have a checkbox which allows the user of the SFX to disable the running of the command line (see setStringData below to see how to set up the command line).  The default is False.

Set to True if you want the SFX dialog to have a checkbox which allows the user of the SFX to disable the running of the command line (see setStringData below to see how to set up the command line).  The default is False.

property UserCanChooseFiles: Boolean);

Set to True if you want the end user of the SFX to be able to select the files in the listbox to be extracted.  If set to False (the default), all files will be extracted.

property UserCanChangeOverwrite: Boolean ;

Set to True if you want the end user to be able to determine the overwrite mode through a set of option buttons on the dialog box.  If set to False, the overwrite mode will be set to the default overwrite mode which you can set using the setOverwriteMode (below), and the end user won't be able to change it.

property OverwriteMode: TsfxOverwriteMode ;

Set to the value you want the default overwrite mode to be.  The default value is omPrompt.  The allowable values are:

  omPrompt	A dialog box will be diplayed asking the user if they wish to overwrite an existing file with the file currently being unzipped.

  omAlways	Always overwrite any existing files.

  omNever	Never overwrite any existing files, do not extract if file already exists.

property AutoRun: Boolean ;

Setting this value to True will cause the SFX to automatically run and extract its contents to the destination path that you set in the call to setStringData (see below).  In this case, upon double clicking, the sfx will automatically run without any intervention from the user.  A window will not appear (unless you assign a value to InfoText in which case an information window will be shown before unzipping commences).  You can still have the sfx execute a program or file when done by setting the CmdLine property.

property Caption: String;

The SFX Dialog's caption

property DefaultPath: String;\

The default extraction directory shown in the dialog's target directory text box.  The user will be able to change this. If set to '><', the files will be extracted to the system temporary directory.  The default is '' which means the directory will first be set at the same directory as where the SFX itself resides. (e.g. "><readme\test.txt" after an extraction to the path "C:\Program files\unpacked" means :  "c:\progra~1\unpacked\readme\test.txt") <- the short path will be created by zipsfx.

property  CmdLine: String;

The command line to execute after all files have been extracted. If the string "><" (greater than+less than) is somewhere in the command line, it will be replaced with the path where the archive has been extracted to.

If the pipe "|" is in the command-line, the part to the left will get the application to run and the part to the right will be it's argument.  if the archive is extracted to e.g. "d:\unpack", then we will get the following :

Command Line	Will parse To:

"><setup\setup.exe|><install.inf"	run "d:\unpack\setup\setup.exe" with parameters  "d:\unpack\install.inf".

"c:\windows\notepad.exe|><readme.txt"	run "c:\windows\notepad.exe" with parameters  "d:\unpack\readme.txt".

"><readme.txt"	open "d:\unpack\readme.txt" with its associated program, if there is any.

"><setup.exe"  	run "d:\unpack\setup.exe" without special parameters.

property InfoText: String;

If InfoText is set to anything, then the first thing the sfx will do when it is run is show a window with this text in it.  This text can be set to whatever you want and it can include carraige returns too.  This information window will be shown even if AutoRun is set to True.

property InfoTitle: String;

This will be the caption shown in the Information Window.


ImproperZip

Applies to

TVCLUnZip

Declaration

property ImproperZip: Boolean;

Description

ImproperZip is a ReadOnly property.  The best place to check the value of this property is after a call to ReadZip. If it has a value of True, then VCLZip detected that the zip file had something wrong with it's file structure and could possibly be corrupted.  If you did not get an exception thrown, VCLZip may have read the zip information ok, but it had to do it in a way that bypassed the problem and so it is not guaranteed that everything is ok.

See Also:

IncompleteZipMode Property

OnInCompleteZip Event

CheckArchive Method

FileIsOK Property


setZipSignatures

procedure setZipSignatures( centralsig, localsig, endsig: LongInt );

Uses KPZIPOBJ;

This procedure allows you to change the header signatures that start each header in the zip file that are created when zipping, and expected when unzipping.  Normal zip files have specific signatures for each header in the zip file.  Changing them will make it so that zip files that you create will not be recognized by other zip utilities.  The main reason for doing this would be for security reasons.  You can use this in addition to Password encryption.

Remember, if you create zips with particular signatures, you will need the same signatures to be set in order to open and unzip the same files.

Also, this is not really a VCLZip method, it is a global method.  So in any application all instances of VCLZip will have the same signatures set at any one time.


BufferedStreamSize

Applies to

TVCLUnZip

Declaration

property BufferedStreamSize : Cardinal;

Description

BufferedStreamSize is the size of the buffer that the Buffered File Stream uses.  By default, all files that VCLZip opens are buffered.  If you have NOSTREAMBUFF defined then this propery has no effect.  This has it's biggest effect on the speed that zip files are written to floppy or other slow media.  The default value for this property is

$8000  (32k) for 16bit Delphi 1

$20000 (128k) for 32bit

These defaults should be good for your average zipping and unzipping, but you may tweak these to best suit your application.


OnPrepareNextDisk

Applies to

TVCLUnZip

Declaration

property OnPrepareNextDisk : TPrepareNextDisk

TPrepareNextDisk = procedure(Sender: TObject; DiskNum: Integer) of Object;

Description

When creating a spanned zip file across removable media, this event is triggered directly after the OnGetNextDisk Event has been processed and just before the zipping process is continued.  This gives you a chance, from this event, to prepare the diskette in any way you wish. This is a good place to put code to format the disk, delete files from the disk, or even add special files if you wish.  After this event is done, the zipping process will continue with that part of the spanned zip file.  DiskNum is the number of the disk that you are working with.  The first disk in the spanned set would be number 1.

Please note that before calling this event, VCLZip will already have deleted any zip files on the disk that match the name of the zip file being created, so you don't have to worry about using this event to do that youself.

See Also:

OnGetNextDisk Event


Version History
Version History for 2.20

Version History 2.18 and Earlier

Version 2.20

Changes have been made in the following areas:

Performance

There are a few code optimizations that should speed up the zipping process slightly.

Spanned Zip Files

A new feature, turned on with the SaveZipInfoOnFirstDisk allows VCLZip to create and read spanned zip files starting with the first disk instead of the normally required last disk of the spanned disk set by saving a Zip Configuration File on the first disk.  This feature can be used even if creating the spanned zip file directly to your hard drive.

A new property, SaveOnFirstDisk, allows you to save room on the first disk when creating a spanned zip file, to allow room for other files, such as setup programs, data files, or a Zip Configuration File.

Spanned zip files can now be directed toward disks greater than 2 gig in size as long as you are using Delphi 5 or BCB 4.

UnZipping

The new Selected indexed property offers another way to flag files to be unzipped.  Files that have the Selected property set to True can be unzipped using the UnZipSelected method.  The Selected property will be cleared (set to False) for each file as it is unzipped, but you can also call the ClearSelected method to clear them all.  At anytime the NumSelected property can be checked to see how many files have been selected.

Also, the UnZipToBufferByIndex and UnZipToStreamByIndex methods allow you to unzip files specified by their index instead of by name or wildcard.

The BufferLength property allows buffered output (buffer smaller than the total uncompressed filesize) when unzipping directly to memory (see UnZipToBuffer and UnZipToBufferByIndex).  This will cause the OnGetNextBuffer Event to be called everytime BufferLength bytes have been output by VCLZip.

Modified to work in all ways with zip files that have "extra fields" in their headers. These tend to be quite rare, but they do show up from time to time.

Zipping

Added a property called FileOpenMode which allows you to define the file open mode for files when they are opened to be zipped.

Added a Retry parameter to the OnSkippingFile Event that can be used to re-attempt to open a file for zipping that is open by another process.  This gives the chance to close the file and continue with the zipping process rather than having to start over again.

Added a ENotEnoughRoom exception which will be thrown if there is not enough room to write to the archive, i.e. out of disk space.

The new OnUpdate Event gets fired when updating or freshening an existing archive.  It is triggered for each file that already exists in the archive as it is either replaced or kept in the updated archive.

The AddDirEntriesOnRecurse will cause separate directory entries to be included in archives when doing recursive zips through subdirectories.

Integrity Checking

A new method, CheckArchive, will perform an integrity check on all files in an archive.  This is much faster than using FileIsOK on each file if testing all files in an archive with VERY MANY files.

Further improved checking for corrupted zip files when opening zip files.

Encryption

The following new properties and methods allow lower level work with password encrypted archives:

DecryptHeader	Gets the decryption header for a particular compressed file in an archive

GetDecryptHeaderPtr	Same as DecryptHeader but easier to use in BCB.

DecryptHeaderByte Method	Tests a password against the decryption header found in the DecryptHeader property.

GetDecryptHeaderByteByPtr	Same as DecryptHeaderByte but easier to use in BCB.

Self Extracting Executables

Modified kpSFXOpt to include

Changes were made to the ZIPSFX32.BIN stub itself:

- Modified to work with zip files containing "extra fields" in their headers. - Modified to change mouse cursor to an hour glass during processing. - Check for correct file size is now done automatically - Now uses the end of central and central headers to find the first local header. - Added a progress meter and - Better checking for corrupted zip files. - Added an information window that can optionally be shown when the sfx is initially started up. - Added an AutoRun option to make the sfx stub run automatially when double clicked with no other interaction from the user.

For the new modified sfx stub, ZIPSFX32.BIN, instead of using kpSFXOpt, you should now use the TSfxConfig component to set the options for the sfx stub.

The new sfx can be found in the sfx\ subdirectory as usual and is called ZIPSFX32.BIN and the original sfx can be found in the same subdirectory except it is now called ORGSFX32.bin.  Just rename it if you prefer that one (use KPSFXOPT instead of TSfxConfig with the old stub).

Miscellaneous

The installation is now easier, atleast for first time installers of the source code.  The .DPK files for Delphi and .CPP files for BCB are now included.  Now these files simply have to be compiled and that's it.  There is a separate option in the installation for installing to the different versions of Delphi and BCB.

Added a property called FlushFilesOnClose which will cause all files opened for write by VCLZip to have their disk buffers flushed to disk when closed.

Added the capability to delete Selected files from an archive using the DeleteEntries Method.

The behavior of the OnInCompleteZip Event has been greatly improved.  You can now use this event to ask the user to insert the last disk of a spanned disk set rather than having to handle this situation from outside VCLZip.

The register procedures were changed so that the components now get installed to the "VCLZip" tab on the palette.  I found that for all but Delphi 1 I had to actually manually move the components to the "VCLZip" tab. You may find that you have to do this too if you have already installed VCLZip before.

The components now use new bitmaps in place of the old ones on the component palette.

Separated many compiler defines into a new file called KPDEFS.INC.


OnRecursingFile

Applies to

TVCLZip

Declaration

property OnRecursingFile: TOnRecursingFile;

TRecursingFile = procedure( Sender: TObject; FName: String ) of Object;

Description

The OnRecursingFile event is called when VCLZip is recursing directories, searching for files that satisfy a wildcard that was entered into the FilesList Property.  It is called for each file that is found that meets the criteria.  The FName parameter contains the filename of the file that was just found that meets the wildcard criteria.

For instance if you did the following:

TVCLZip.Recurse := True; TVCLZip.RootDir := 'c:\mydirs'; TVCLZip.FilesList.Add('*.pas'); NumZipped := TVCLZip.Zip;

This event would be called for every .PAS file as it is found while VCLZip recurses the 'c:\mydir' directory and all of it's subdirectories.

All recursing is done prior to any actual zipping.  So this is a good way to show some sort of progress when you are recursing a large directory structure, otherwise your application may seem to be hung while the recursing is progressing.  Note that there can still be a long time between event calls if most files in a very large directory structure do not match the wildcard.

For example in your OnRecursingFile event you may wish to do something like the following:

procedure MyForm.OnOnRecursingFile( Sender: TObject; FName: String );

begin

StatusLabel.Caption := FName + ' matches wildcard and will be zipped';

end;